frevvo supports the Azure Security Manager for Single Sign On. Users/roles are automatically pulled from Azure AD into frevvo cloud tenants and on-premise installations. Users are redirected to the Microsoft Azure login screen for authentication.

frevvo recommends using the SAML Security Manager for customers who want to manage users/roles from the frevvo UI.

On this page:

Prerequisites

Microsoft Azure

You will need a valid Microsoft Azure subscription.

Roles

Required: The frevvo.TenantAdmin and frevvo.Designer groups must be specified on your Active Directory server. The group names must be spelled as shown. Upper/lower case may be a factor for Open LDAP systems. These groups are required.

Tenant admin users must be assigned to the frevvo.TenantAdmin group.
Designer users must be assigned to the frevvo.Designer group

Optional: There are two additional roles in frevvo - frevvo.Publisher and frevvo.ReadOnly. These roles are optional.

In order to give a user the frevvo.publishers role, create the frevvo.Publisher group in your AD and assign users to it. Refer to the Publisher Role Documentation for an explanation of this role.
In order to give a user the frevvo.ReadOnly role, create the frevvo.ReadOnly group in your AD and assign users to it. Following frevvo Best Practice eliminates the need for this role.

Other than these four groups, please do not name any other Azure groups with the 'frevvo.' prefix as this can cause problems reading user details.

Contact the frevvo Customer Success team to schedule your Security Manager configuration.
frevvo Best Practice recommends that you create a user account in your Active Directory that will house all of your deployed Production forms/workflows. This user can be named anything i.e.frevvoProduction but it must be a member of the frevvo.Designer group
Review the documentation on Preserving Projects/Forms/Workflows developed in your trial/starter tenant BEFORE changing security managers.
frevvo only supports the Azure Security Manager when frevvo is running in the tomcat container. Refer to our Supported Platforms for the list of supported/certified Application Servers.

Configuring the Azure SAML Security Manager

Follow these steps listed below to create a frevvo tenant using the Azure SAML Security Manager:

Step 1 - Create an Application for frevvo in Azure

frevvo assumes that customers have someone on staff that can successfully perform this step of the procedure. Information about frevvo is listed below to help you with this process.

The Azure global administrator MUST create the application for frevvo in Azure.

If you are familiar with the Microsoft Azure Legacy Portal, review this Microsoft Training Guide before setting up the Azure application for frevvo.

Do not include the curly braces in the URLs discussed below.

Log in to the Microsoft Azure Management console: https://manage.windowsazure.com or https://portal.azure.com with your Azure global administrator account.
Click on the Azure Active directory link on the left side of the screen.
Click on the App Registrations link.
Click on the New application registration link for creating a new application.
Enter the following details:
1. Name:- Name of your frevvo Azure application
2. Select who can use this application or access this API
Configure the Redirect URL:
1. Cloud Customers should use https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/{t} - replace {t} with the name of your frevvo tenant.
  
  For example, if you were changing the Security Manager from the Default Security Manager to the Azure SAML Security Manager for a frevvo Cloud tenant named mycompany.com, the REPLY URL would be:
  https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/mycompany.com
2. On-premise customers should use https://<server>:<port>/frevvo/web/saml/SSO/alias/{t} - replace <server> with the ip of your server, <port> with the port number (if applicable) and t with the name of your frevvo in-house tenant.
  
  For example, if you were changing the Security Manager from the Default Security Manager to the Azure SAML Security Manager for a frevvo in-house tenant named mycompany.com, the REPLY URL would be:
  https://<server:port>/frevvo/web/saml/SSO/alias/mycompany.com
3. Click Register.
Select the frevvo application from the list.
Click the Branding tab
Configure the Home Page URL:
1. Cloud Customers should use https://app.frevvo.com:443/frevvo/web/tn/{t}/login - replace {t} with the name of your frevvo Cloud tenant.
  
  For example, if you were changing the Security Manager from the Default Security Manager to the Azure SAML Security Manager for a frevvo Cloud tenant named mycompany.com, the SIGN-ON URL would be:
  https://app.frevvo.com:443/frevvo/web/tn/mycompany.com/login
2. On-premise customers should use https://<server>:<port>/frevvo/web/tn/{t}/login - replace <server> with the ip of your server, <port> with the port number (if applicable) and t with the name of your frevvo in-house tenant.
  
  For example, if you were changing the Security Manager from the Default Security Manager to the Azure SAML Security Manager for a frevvo in-house tenant named mycompany.com, the SIGN-ON URL would be:
  https://<server:port>frevvo/web/tn/mycompany.com/login
3. Click Save.
Click on the API Permissions tab.
1. Click Add a Permission.
2. Select Microsoft Graph.
3. For Application Permissions, select Directory.Read.All and optionally Directory.ReadWrite.All (under Directory).
4. For Delegated Permissions, select User.Read. (This permission may already be present.)
5. Click on the Grant Permissions button select "Yes" option and click on the Save button.

Click on the Expose an API tab.

Click Add a Scope. See this Microsoft Azure documentation for details.

By default, Azure provides the ApplicationID URI as api://<appId>.For example

api://3f2fd3fd-67f5-423e-95bc-c01d3712966c

You may use a different AppID URI if desired. This table lists supported* formats:

api://<appId>	api://fc4d2d73-d05a-4a9b-85a8-4f2b3a5f39fe
api://<tenantId>/<appId>	api://a8573488-ff46-450a-b09a-6eca0c6a03ed/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f39fe
api://<tenantId>/<string>	api://a8573488-ff46-450a-b09a-6eca0c6a03ed/api
api://<string>/<appId>	api://productapi/fc4d2d73-d05a-4a9b-85a8-4f2b3a5f39fe

*See this Microsoft documentation for additional available formats. frevvo has not verified every format, so please use those not listed here with caution.

Click Save and Continue.
Provide the required attributes and choose a consent option. Usually, this will be Admins and Users.

Click the Certificates & secrets tab.
1. Generate the Client Secret. Copy the new secret's Value and save it in a notepad - you will need this for the frevvo tenant screen.
Click the Overview tab.
1. Copy the Application ID into your notepad. This is the value of the Client ID on the frevvo configuration screen.
2. Copy the Directory ID into your notepad. This is the value of the Tenant ID on the frevvo configuration screen.
  Click Endpoints at the top of the screen. Copy the Federation Metadata Document URL from the list to your notepad. This is the URL that you will use to generate the Azure metadata
  Example of the Federation Metadata Document URL
```
https://login.microsoftonline.com/3d532ac1-a43c-45c7-b0e9-cc814400ca11/federationmetadata/2007-06/federationmetadata.xml
```
Proceed to Step 2 - Create the frevvo metadata file

Just a reminder - you will need the Azure tenant ID, the client id and client secret for the frevvo application when configuring your frevvo Azure SAML tenant.

We recommend making a note of your Client Secret expiration date. You will need to refresh it prior to the expiration to ensure continued access to frevvo. See this Microsoft article for details.

Step 2 - Create the frevvo metadata file

Follow these steps to generate the frevvo metadata for your Azure SAML tenant. You can do this even if the tenant has not been created yet.

Paste this URL into your browser:

Cloud Customers: https://app.frevvo.com:443/frevvo/web/saml/metadata/alias/{t} - replace {t} with the name of your frevvo tenant - Ex; azuread
On-premise customers: https://<server>:<port>/frevvo/web/saml/metadata/alias/{t} - replace <server> with the ip of your server, <port> with the port number (if applicable) and t with the name of your frevvo tenant.

When the metadata displays, save the page as an xml file.

Edit the .xml file. Replace the entityID property (shown here on line 2) with the AppId URI (see Step 1 bullet #11) from Azure. For example, the generated entityID will look like this

Generated entityID

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="https___localhost_8443_frevvo_web_alias_testazuread" 
entityID="https://staging-app.frevvo.com:443/frevvo/web/alias/qateam_azure">

Replace the generated entityID with your AppId URI like this

Updated entityID

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="https___localhost_8443_frevvo_web_alias_testazuread" 
entityID="api://d8447c40-ac18-487c-a9a1-dc63d9f4a866">

Copy the entire metadata from this file to the Azure SAML Security Manager configuration screen.

Metadata must be generated for each Azure SAML tenant. Each tenant will have a unique URL.

Step 3 - Create the Azure Tenant Idp metadata file

Follow these steps:

Browse the Federation Metadata Document URL that you copied to your notepad when creating the Azure application for frevvo. It is located on the Endpoints tab in your frevvo Azure application.

Example of Federation Metadata Document URL from Endpoints

 https://login.microsoftonline.com/fece6b7e-fbc6-4b3a-8287-fc07c29aa2d2/FederationMetadata/2007-06/FederationMetadata.xml

Save all the metadata returned as an xml file. We will need to copy the entire metadata from this file to the Azure SAML Security Manager configuration screen.

Step 4 - Create/edit the Azure SAML tenant

To successfully create a frevvo tenant using the Azure SAML Security manager, you will need the following:

frevvo metadata file
The Azure SAML tenant Idp metadata file
Attribute mapping information
The Azure tenant ID, the client id and client secret key that are created as part of registering the frevvo application.

The following steps must be taken by the superuser or tenant admin on the Add/Edit Tenant page.

Select Azure SAML Security Manager from the Security Manager Class dropdown. (If changing from default or LDAP, click "Change", then select the Azure SAML Security Manager.)
Paste Metadata.
1. frevvo is the "Service Provider." Copy the frevvo metadata into the Service Provider Metadata field. You can include the xml prolog when you paste the Service Provider (frevvo) metadata.
2. Azure is the "Identity Provider". Copy the Azure tenant metadata and paste it into the Identity Provider Metadata field.
3. URL: Enter the Federation Metadata Document URL that you copied from Endpoints in your frevvo Azure application. The URL is needed to handle Signing key rollover in Azure Active Directory. This URL is polled and refreshes the Azure IDP metadata every 3 hours. The new metadata is stored and automatically used as backup in case the URL is not accessible.
  Example of Federation Metadata Document URL
```
https://login.microsoftonline.com/fece6b7e-fbc6-4b3a-8287-fc07c29aa2d2/FederationMetadata/2007-06/FederationMetadata.xml  
```
Apply All Groups and/or All Users Filters (optional). By default, frevvo will read all users and all groups. You may apply a filter to limit this for users and/or groups. To apply a filter, you should have knowledge of the specific user/group properties and the correct syntax; please see this Azure filter documentation for supported operators and functions. There is no filter validation on the Edit Tenant page. For example, if you have groups specific to frevvo workflows that begin with "frevvo" you can set your groups filter to startsWith(displayName, 'frevvo'); if you want to limit frevvo users to only your domain, your users filter could be endsWith(userPrincipalName,'@doccuphasesandbox.onmicrosoft.com').
Check the Ignore Case checkbox if you are using LDAP for authentication and you want frevvo to ignore the case stored in LDAP systems for users/roles. The field is checked by default. Refer to the Mixed or Upper case User Names topic for more information.
Enter the User Id. This should be the User property name that identifies the user. A typical value is userPrincipalName, mailNickname, etc.
Optional: Custom attributes can be mapped by typing the attribute names in the Custom field separated by a comma.

Enter the following information in the API Access section.

Enter the Azure tenant identifier into the tenant Id field. This can be obtained by viewing the endpoint Urls listed when you click View Endpoints in your frevvo Azure application.
Enter the client id and client secret key that were created as part of registering the frevvo application into the respective fields.

New Tenants

Configure a tenant admin account. This account does not require Azure SAML authentication. This tenant admin can log directly into frevvo.

The tenant admin id, password and email fields are required. The Change password on next login is optional. It is checked by default.
When this tenant admin performs a form-based login i.e. /frevvo/web/login, the password entered on this screen is used for authentication. This is also the URL used by the API. For cloud customers the <base> is always https://app.frevvo.com.
If the tenant based login url is used i.e. /frevvo/web/tn/{t}/login then the Azure SAML login is used.

The forgot password function works for an Azure SAML tenant admin user. For all others, it will display the error message about not being supported for the tenant.

Configure the Business Calendar for your tenant. The frevvo escalation feature will use this calendar to calculate deadlines and send notifications and reminder emails.

Enter HTTP Auth credentials if required. Credentials for external secure web services accessed by the forms and workflows in your tenant can be specified in this section.

Click Submit.

Step 5 - Logging into a frevvo Azure SAML Tenant

Paste this tenant-specific URL into your browser:

Cloud Customers: https://app.frevvo.com:443/frevvo/web/tn/{t}/login - Replace {t} with the name of your Azure SAML tenant.
On-premise Customers:http://<server>:<port>/frevvo/web/tn/{t}/login. Replace <server> and <port> with your server information and t with the name of your Azure SAML tenant.
The user is redirected to the Azure login screen.
If the user is authenticated, frevvo screens display depending on the level of authorization specified for the user. Designer users will see the Projects Home Page while non-designer users will be directed to their Task List. You will see this redirection when logging into a frevvo portal as well.

Clicking the logout link in frevvo, logs the user out from frevvo only.

When a user logs in to portal, the logout link will not be visible in an Azure AD (SSO) tenant.

When a user logs in to frevvo (non-portal mode), the logout link will be visible in an Azure AD (SSO) tenant.

Cloud customers browsing app.frevvo.com or in-house customers browsing http://<servername>:<port>/frevvo/web/login attempting to log into an Azure tenant directly (user@saml tenant name) will automatically be redirected to the Azure IDP login page.

Logged in User Display in Azure SAML frevvo tenant

If your Azure SAML userIds are in the format <username>@<domain name>, when you log in to frevvo the frevvo tenant name is appended to the userId . This is as designed. You will see <username@domain name@frevvo tenant name> as the logged-in user at the top of the screen. If your domain name is the same as your frevvo tenant name, it will appear as if the domain name is listed twice.

Azure SAML Tenant Built-in Admin User

Just a reminder that the tenant admin account can login directly into frevvo or use the Azure SAML login.

When you create/edit a new tenant you are prompted to set up/modify a tenant admin user id, password and email address. This tenant admin does not authenticate via your Azure SAML IDP. It only exists in frevvo. If you experience an issue with your Azure SAML configuration such that you can't login as an Azure SAML authenticated user, use the built-in admin user to login to your tenant as a tenant admin in order to fix your Azure SAML configuration issue. Only one built-in tenant admin account is supported.

Browse this URL to login as the built-in: <base_URL>/frevvo/web/admin/login. When specified, frevvo will prepend the base URL to the URLs in your Form/Document Actions. The <base_URL> is typically http(s)://<your servername>:<port>.

You must use the admin-specific URL - <base-url>/frevvo/web/admin/login - to login as the built-in.

Non-admin users can also log in using the admin-specific URL.

If your tenant originally used the Default Security Manager and then you changed to the Azure SAML Security Manager, this tenant admin account has already been set up. If you have forgotten the password, you can change it by :

Browsing the admin specific URL - <base-url>/frevvo/web/admin/login. Enter the built-in userid. Click Forgot Password? This error message displays if any other user clicks on the Forgot Password? link after browsing the admin-specific URL:

Logging in as an Azure SAML authenticated tenant admin and changing the password via Manage Users.

The frevvo superuser admin (Cloud customers) and the in-house superuser can change the password for the built-in userid from the Edit Tenant page.

What if you do not remember the userid of your original tenant admin? Follow these steps:

Click Manage Users and click the edit admin icon.

The frevvo (Cloud customers) and in-house superuser can see the built-in tenant userid from the Edit Tenant page.

Session Timeout

Session timeouts are configured in frevvo and in your Azure SAML IDP. If a user's session ends before the IDP timeout is reached, they will automatically be logged back into frevvo if they try to access it again. It is recommended that the frevvo session timeout and the IDP session timeout be configured for the same value.

Embedding Forms/Workflows in your website

Embedding forms and workflows into your website when using the Azure SAML Security Manager, will work in the following scenarios :

The visibility of the form is set to Public.

The visibility of the form is set to Public in Tenant and the user is already authenticated to Azure SAML

Embedding forms and workflows into your website is NOT supported if the visibility of the form is set to Public in Tenant and the user is NOT already authenticated to Azure SAML. This is because frevvo must direct the user to the IDP login screen and the browser will not allow loading the IDP login page in frevvo's form iframe.

Retrieving Custom Attributes from Azure Active Directory in an Azure SAML Tenant

The Azure AD Graph API allows access to users, groups, etc... in Azure AD. User entity attribute data exposed by the API for the logged-in user can be pulled into fields in your form/workflow with a business rule. If the attribute that you are looking for is not already exposed, you can:

Sync Azure AD to your in-house AD via the Microsoft-provided connector

Add an extension property

Once the custom attributes are made available, add them to the Custom section of your Azure SAML tenant.

Click the Edit Tenant link

Add the custom attributes to the Custom section as a comma-separated list. The image shows the department and displayName attributes listed in the custom attribute section.

Design your form/workflow with fields to collect the information.

Write a business rule to populate the controls with the custom attribute information.

Here is an example of a rule that will retrieve the custom attributes, department, and displayName, plus the standard attributes, First Name, Last Name, and Email address.

if (form.load) {
    FirstName.value = _data.getParameter('subject.first.name');
    LastName.value = _data.getParameter('subject.last.name');
    EMail.value = _data.getParameter('subject.email'); 
    department.value = _data.getParameter('subject.department');
    displayName.value = _data.getParameter('subject.displayName');
}

Using the SharePoint Connector in an Azure SAML Security Manager tenant

At least one designer user that is going to be connecting forms/workflows to SharePoint with the Save to SharePoint wizard must also be a SharePoint user with the correct privileges to provide consent if your tenant is configured with the Azure SAML Security Manager .

Troubleshooting

Application Error Logging in the Azure SAML tenant

If you see an application error when logging in and an error message, "Caused by: org.opensaml.common.SAMLException: InResponseToField of the Response doesn't correspond to sent message", in the logs, your Azure secret key may have expired. See this article for steps to renew it. Then update the frevvo tenant (Step 4 above).

Logging into an Azure SAML tenant as (user@Azure SAML tenant name)

Logging into an Azure SAML tenant as (user@Azure SAML tenant name) displays an application error message.

On-premise customers using the tomcat bundle will see the following entry in the frevvo error log:

Application error processing /frevvo/web/login?null java.lang.UnsupportedOperationException: null

Accessing a portal in an AzureAD tenant on a mobile device will not display a logout button.

Skew error when logging into an Azure tenant

Users logging into a frevvo Azure SAML tenant may encounter the error "Access Denied. Authorization Required". Examination of the frevvo.log shows the following entry:

Response issue time is either too old or with date in the future, skew 60, time 2016-06-01T05:49:25.330Z

This error is typically caused by a clock synchronization issue between the SP (frevvo) and the Idp (Azure) or a genuine delay in the connection. If you get this error, you can change the value of the context parameter, com.frevvo.security.saml.response.skew, to specify the time in seconds allowed between the SAML request and response to a value greater than the default value of 60 seconds.

Follow the instructions listed in the Installation Tasks chapter to add the parameter.

Login into the frevvo Azure SAML tenant fails

If the login into your Azure SAML tenant fails and the frevvo log reports the following error, you may have to edit your Azure SAML tenant to add the metadata URL. T

org.opensaml.xml.validation.ValidationException: Signature is not trusted or invalid.

The URL is needed to handle Signing key rollover in Azure Active Directory. This URL is polled and refreshes the Azure IDP metadata every 3 hours. The new metadata is stored and used as backup in case the URL is not accessible. Refer to Step 6 above for the details.

Cannot get User Details

If you see an error like "cannot get user details" when using business rules to populate user info, please ensure that your Azure groups do not include "frevvo." in the name (other than the 4 roles mentioned above: frevvo.Designer, frevvo.TenantAdmin, frevvo.Publisher, and frevvo.ReadOnly.)

Azure SAML Errors

The table below lists errors you may encounter when configuring your tenant with the Azure SAML Security Manager. Verify the recommended values to resolve.

Parameter	Value to Verify	Error on Edit Tenant Page	Error While Accessing Tenant
SP metadata	Use a domain for which an application is not added in Azure	No issue updating tenant	Login will redirect to Microsoft login. After entering credentials, following appears on the page: Sorry, but we’re having trouble signing you in. We received a bad request. Additional technical information: Correlation ID: 4a94d6f0-fcab-4953-8a4b-252cc18e938a Timestamp: 2017-11-03 10:03:44Z AADSTS70001: Application with identifier 'http://example.com:8082/frevvo/web/alias/testlink' was not found in the directory fece6b7e-fbc6-4b3a-8287-fc07c29aa2d2 No logs in frevvo
	Invalid XML	org.opensaml.xml.parse.XMLParserException: Invalid XML
	Removed contents from metadata: <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="http___localhost_8082_frevvo_web_alias_testplan" entityID="http://localhost:8082/frevvo/web/alias/testlink"> </md:EntityDescriptor>	No issue updating tenant	Application Error javax.servlet.ServletException: org.opensaml.saml2.metadata.provider.MetadataProviderException: No local entity found for alias testlink, verify your configuration. Logs : same exception with stack
IdP metadata	Do not remove Signature and RoleDescriptor sections	Tenant added successfully	No errors but we should not use it (https://www.identityguy.com/articles/2013/6/4/a-look-at-azure-ads-web-sign-in-endpoints.html)
	Removed certificates(<X509Certificate>) from IdP metadata xml	Tenant added successfully	No errors as we are providing the URL for IdP
Tenant Id	Wrong value	UI : Group access failure: HttpClientErrorException: 400 Bad Request Logs : Same exception with stack	NA
Client Id	Wrong value	UI : Group access failure: HttpClientErrorException: 400 Bad Request Logs : Same exception with stack	NA
Client Secret	Wrong value	UI : Group access failure: HttpClientErrorException: 401 Unauthorized Logs: Same exception with stack	NA
User Id	Wrong value	UI : User access failure: HttpClientErrorException: 400 Bad Request Logs : same with stack	NA
Tenant ID in frevvo	A value for which metadata was not generated and app was not created in Azure AD	Tenant updated successfully	UI : Access Denied. Authentication required. Logs: 2017-11-03 16:36:50.152 WARN diff a416e8eb-d7d2-4d30-a7cc-fb7ceb7a5814 776 --- [http-nio-8082-exec-10] com.frevvo.forms.web.LoginResource : Login failure org.springframework.security.authentication.AuthenticationServiceException: Error determining metadata contracts log contains stack trace
Admin user id	A value not present in AD	Tenant updated successfully	No errors. users can login and use frevvo. admin@frevvo.com still has tenant admin properties.

Browser not supported