Prerequisites

When you create an Azure SAML tenant in , the Authentication Only option is checked by default. frevvo assumes that most customers will want to use Active Directory for users and roles so this option is hidden on the Tenant screen. In Authentication Only mode, users and roles have to be defined in your AD.  

For example, customers using Azure Active Directory must ensure that the frevvo.TenantAdmin and frevvo.Designer roles are specified for tenant admin and designer users.

These groups map to the roles in  which are case sensitive. Make sure assigned group names are added in the correct case. Users with these groups may have to be added to the application created in Azure to gain access. See the tips below for more information.

Configuring the Azure SAML Security Manager

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

1. Create an Application for Live Forms in Azure
2. Create the Live Forms metadata file
3. Create the Azure Tenant Idp metadata file
4. Create/edit the Azure SAML tenant
5. Log into your Live Forms Azure SAML tenant

Step 1 - Create an Application for Live Forms in Azure

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

1. Login to the Microsoft Azure Management console: https://manage.windowsazure.com

2. Click the Azure classic portal panel to switch to the classic view.

   
   
   

3. Add a new application under the Active Directory tab.
4. In order to complete the single sign-on fields:
   1. AP ID URI:
      

      1. Cloud Customers should use https://app.frevvo.com:443/frevvo/web/alias/{t} - replace {t} with the tenant id of your frevvo Azure SAML tenant.

      2. On-premise customers should use http://<server>:<port>/frevvo/web/alias/{t} - replace <server> with the ip of your server, <port> with the port number (if applicable) and t with your frevvo Azure SAML tenant id.

   2. REPLY URL:
      

      1. Cloud Customers should use https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/{t} - replace {t} with the tenant id of your frevvo Azure SAML tenant.

      2. On-premise customers should use http://<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 your frevvo Azure SAML tenant id.

   3. SIGN-ON URL
      

      1. Cloud Customers should use https://app.frevvo.com:443/frevvo/web/tn/{t}/login - replace {t} with the tenant id of your frevvo Azure SAML tenant.

      2. On-premise customers should use http://<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 your frevvo Azure SAML tenant id.

5.  Click here for some more tips.

   You must be in the Azure classic portal view to see the screens shown below:

   1. Be sure to set up the application permissions to allow the graph API to read the directory in order to retrieve users and groups. Click here to see an example.
      
      
      
      

   2. You will need the Azure tenant ID, and the client id and client secret key that are created for the frevvo application when configuring your Azure SAML tenant.

      1. The client id is displayed on the Confiigure screen of the application for in Azure. An example is shown in the image:
         
      2. The tenant id for application that you created in Azure for can be obtained by viewing the endpoint Urls listed when you click View Endpoints icon at the bottom of the page. See the example in the image:
         
         
      3. There is only one chance to retrieve the client secret key when you create the application for in Azure. In the keys section on the CONFIGURE screen, select an option for the application duration. Click the SAVE icon on the bottom menu to display the client secret key. Copy the key and save it so you have it available when you create your Azure SAML tenant in .
         

         
         
         

      4. One way to restrict access to for specific Azure AD users only, is to:
      • Make sure the USER ASSIGNMENT REQUIRED TO ACCESS APP is set to YES
      • Add users to the application under the USERS tab.
      1. Groups listed under the GROUPS tab in Active Directory map to roles. Refer to Prerequisites for more information.

Step 2 - Create the Live Forms 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.

1. Paste this URL into your browsr:

   1. Cloud Customers: https://app.frevvo.com:443/frevvo/web/saml/metadata/alias/{t} - replace {t} with the tenant id of your Azure SAML tenant - Ex; azuread

   2. On-premise customers: http://<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 your tenant id).

2. When the metadata displays, right click and select the browser option to View the Page source.
   
   
   
   

3. Save the page as an xml file.
4. 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:

1. Browse the azure tenant (IdP) metadata at: https://login.microsoftonline.com/{azure-tenant-name}/FederationMetadata/2007-06/FederationMetadata.xml - replace {azure-tenant-name} with the id of your  application in the Azure Active Directory. This can be obtained by viewing the endpoint URLS listed when you click View Endpoints in your frevvo Azure application. In this example, fece6b7e-fbc6-4b3a-8287-fc07c29aa2d2 is the application id in Azure Active Directory.

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

2. Copy the source of the IDP metadata XML and save it as an xml file. 

Step 4 - Create/edit the Azure SAML tenant

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

• 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.

cloud customers, migrating your tenant to the Azure SAML Security Manager, will make the changes via the Edit Tenant screen. Once accessed, follow these steps beginning with step 3.

1. Log onto as the superuser (on-premise) or the tenant admin (cloud).
2. Access the Add Tenant (on-premise) or Edit Tenant (cloud) screen.
3. Select Azure SAML Security Manager from the Security Manager Class dropdown.
4. Copy the Service Provider (frevvo) metadata into the Service Provider field. You can include the xml prolog when you paste the Service Provider (frevvo) metadata.
   
   
   
   
5. Copy the metadata from the Azure tenant IDP file previously created and paste it into the Identity Provider field.
   
   
   
   

6. Enter the URL that you used in Step 3 to generate the Azure IDP metadata into the URL field below the Identity Provider section. 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.
   

   In this example, fece6b7e-fbc6-4b3a-8287-fc07c29aa2d2 is the  application id in Azure Active Directory. It was obtained by viewing the endpoint URLS listed when you click View Endpoints in your frevvo Azure application.

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

7. Check the Ignore Case checkbox if you are using LDAP for authentication and you want 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.

8. The Authentication Only checkbox enables SAML to handle authentication only when checked. In this mode, authorization happens based on the roles defined in Azure AD.  Authentication Only mode is recommended if you are using the Azure SAML Security Manager. It is checked by default and the field is hidden on the screen.

9. Enter the User Id. This should be the User property name that identifies the user. A typical value is userPrincipalName, givenname etc.
   

10. Custom attributes can be mapped by typing the attribute names in the Custom field separated by a comma.
11. Enter the following information in the API Access section.
    1. 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.
    2. Enter the client id and client secret key that were created as part of registering the frevvo application into the respective fields.
       
       
       
12. Configure a tenant admin account. This account  does not require Azure SAML authentication. This tenant admin can log directly into Live Forms providing a default security manager backdoor.
    
    1. The tenant admin id, password and email fields are required.
    2. 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.
    3. 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.
       
       
       
       
13. Configure the Business Calendar for your tenant. The escalation feature will use this calendar to calculate deadlines and send notiifcation and reminder emails.
14. Enter HTTP Auth credentials if required. Credentials for external secure web services accessed by the forms and flows in your tenant can be specified in this section.
15. Click Submit. 
    

Step 5 - Logging into a Live Forms Azure SAML Tenant

1. Paste this tenant specific URL into your browser:

   1. Cloud Customers: https://app.frevvo.com:443/frevvo/web/tn/{t}/login - Replace {t} with the name of your Azure SAML tenant.

   2. 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.

   3. The user is redirected to the Azure login screen.
      
      
      
      

   4. If the user is authenticated,  screens display depending on the level of authorization specified for the user. Designer users will see the Application Home Page while non-designer users will be directed to their Task List.
      
      
      
      

   You will see this redirection when logging into a space as well.

Azure SAML Tenant backdoor admin user

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

When you create a new tenant you are prompted to set up a tenant admin user id and password. This tenant admin does not authenticate via your Azure SAML IDP. It only exists in Live Forms. If you experience an issue with your Azure SAML configuration such that you can't login as an Azure SAML authenticated user, this account provides a backdoor you can use to login to your tenant as a tenant admin in order to fix your Azure SAML configuration issue. Only one backdoor tenant admin account is supported.

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 setup. If you have forgotten the password, you can change it by :

• Using the Live Forms Forgot Password? feature for the tenant admin account.
• Logging in as a Azure SAML authenticated tenant admin and changing the password via Manage Users.
  

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

1. Login as your authenticated Azure SAML tenant admin
2. Click Manage Users and click the edit admin icon.

Troubleshooting

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

Logging into a 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  error log:

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

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

Skew error when logging into an Azure tenant

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

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 Azure SAML tenant fails

If the login into your Azure SAML tenant fails and the 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.

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/flow 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.

1. Login to your Azure SAML tenant as the as the tenant admin.
2. Click the Edit Tenant link
3. 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.
   
   
   
   
4. Design your form/flow with fields to collect the information.
5. Write a business rule to populate the controls with the custom attribute information.
   
   

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');
}