Image Removed

Prerequisites

Authentication Only mode:

When you create your  SAML tenant, you can select Authentication Only mode..This is done by checking a checkbox when you configure your SAML tenant.

If Authentication Only is selected, SAML is used only for authentication. Authorization depends on the roles defined in .  SAML will authenticate the user but not retrieve any of the attributes.
You may choose to use this mode if you:

• do not want to add  roles to your LDAP.

• LDAP has many roles that have no relevance to your workflow.

• Find the SAML mapping for the other required attributes complex. For example, retrieving the manager user id and role names may require writing custom rules.

...

• User discovery:

  • There is no guarantee that the first login will occur before a task is created for a specific user /role. If you have workflows, that are routed to users who have not logged in yet, your workflow may not do what you expect. If the user’s role changes after 1st login but before the next task is routed to their new role, the task will not appear on their Task List. For example, a user with the role of employee, logs into . The user then gets prompted to manager. The user will not receive a task routed to the user's new role of manager. workflow is initiated before the user logs out and logs in again and the user account is updated.

  • Manually creating/uploading users and roles ahead of time avoids this situation.
    

...

Configuring the SAML Security Manager

In the directions given below, the Service Provider refers to frevvo . The metadata for your SAML tenant must be obtained first. Customers will need to configure the metadata when creating the SAML tenant.

1. In-house Customers Only
   1. Generate Your Certificate
   2. Install the Java Cryptography Extension API
2. Create the frevvo Metadata file.
3. Configure your Identity Provider
4. Create/edit the SAML tenant
5. Manage Users/Roles for your SAML tenant
6. Logging into Live Forms in a SAML Tenant

Step 1 - In-house Customers Only

Cloud customers can skip the Generate Your Certificate and Install the Java Cryptography steps. These instructions are provided for On-premise customers only.

Generate Your Certificate

If you re using the frevvo tomcat bundle, the supplied keystore, frevvoKeystore.jks is located in the <frevvo-home>/tomcat/lib folder, The keystore contains a default certificate with alias=frevvo and password=p@ssw0rd. Replace this  with a certificate for your installation.

...

This certificate is used to sign/encrypt the SAML request. The use of a long-lived self-signed certificate is recommended.

Since the keystore is located outside the frevvo war, you can use the Java keytool to generate and store your certificates. Folllow these steps:

1. Login as administrator.

2. Delete the existing certificate:

   Code Block
   keytool -delete -alias frevvo -keypass p@ssw0rd -keystore frevvoKeystore.jks -storepass p@ssw0rd

3. Generate a new certificate: Here is the command: Change the -dname value to the DNS name of your IDP

   Code Block
   keytool -genkey -dname "cn=app.frevvo.com" -alias frevvo -keypass p@ssw0rd -keystore frevvoKeystore.jks -storepass p@ssw0rd -keyalg rsa -keysize 2048 -validity 3650

4. The certificate can be viewed (and used in the metadata XML) by exporting it to a file:
   

   Code Block
   keytool -exportcert -alias frevvo -file frevvo.rfc -rfc -keystore frevvoKeystore.jks -storepass p@ssw0rd

Install the Java Cryptography Extension

The Java Cryptography Extension (JCE) provides a uniform framework for the implementation of security features in Java. These files are needed to avoid an i"llegal key size" error which can happen if these files are missing in the Java Development Kit (JDK) software of your on-premise installation.

Follow these steps to install the JCE files into the JDK:

1. Go to the Oracle Java SE download page http://www.oracle.com/technetwork/java/javase/downloads/index.html
2. Scroll down … Under "Additional Resources" section you will find "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File"
3. Download the version that matches your installed JVM  - for example, download UnlimitedJCEPolicyJDK8.zip if you are using JDK/JRE version 8
4. Unzip the downloaded zip. 
5. Copy local_policy.jar and US_export_policy.jar to the <JAVA_HOME>/jre/lib/security (Note: these jars are already there so you have to overwrite them)
6. Restart .

Step 2 - Create the Live Forms Metadata file

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

Paste this URL into your browsr:

...

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

...

Step 3 - Configure Your Identity Provider

1. Configure the Service Provider metadata for your Identity Provider. For example, the Shiboleth Identity provider requires modification of a file to provide the path to the tenant metadata xml file created above.
2. Your Identity Provider must be configured to expose the attributes that requires. Attribute mapping is done when you create the SAML tenant. These are:
   1. User Id
   2. First Name
   3. Last Name
   4. Email
   5. Manager Id (optional)
   6. Groups
   7. Custom Attributes (optional)

We know that your IDP software of choice is outside of the frevvo server software and that you have the expertise in house to install, configure and maintain your IDP software. But here are some tips we have found that may assist you.

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> add(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ManagerDN"), query = ";Manager;{0}", param = c.Value); 

Manager SAM1
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ManagerDN"]
=> add(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ManagerSam", Value = RegExReplace(c.Value, ",[^\n]*", ""));

ManagerAccountName
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/ManagerSam"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/manageraccountname", Value = RegExReplace(c.Value, "^CN=", ""))

Configure Custom Attributes

Active directory attributes other than the standard First Name, Last Name or Email are considered custom attributes. You can retrieve custom attributes in addition to the standard ones from Active Directory and pull the data into your form/flow using Live Forms business rules.
For example,let's say you want to extract the custom attribute, StaffId, from LDAP and populate fields in your form/flow using a business rule.

Perform these general steps:

Image Removed

if (form.load) {
  StaffID.value =  _data.getParameter('subject.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/staffid');
}

Image Added

Prerequisites

Authentication Only mode:

When you create your  SAML tenant, you can select Authentication Only mode..This is done by checking a checkbox when you configure your SAML tenant.

If Authentication Only is selected, SAML is used only for authentication. Authorization depends on the roles defined in .  SAML will authenticate the user but not retrieve any of the attributes.
You may choose to use this mode if you:

• do not want to add  roles to your LDAP.

• LDAP has many roles that have no relevance to your workflow.

• Find the SAML mapping for the other required attributes complex. For example, retrieving the manager user id and role names may require writing custom rules.

In this mode, manual creation of users & roles in the  tenant is required. The  CSV upload feature makes this easy.

If Authentication Only is not selected, users will be added (discovery) at runtime when they log in for the first time. It is important to consider the following points before making your decision.

• User discovery:

  • There is no guarantee that the first login will occur before a task is created for a specific user /role. If you have workflows, that are routed to users who have not logged in yet, your workflow may not do what you expect. If the user’s role changes after 1st login but before the next task is routed to their new role, the task will not appear on their Task List. For example, a user with the role of employee, logs into . The user then gets prompted to manager. The user will not receive a task routed to the user's new role of manager. workflow is initiated before the user logs out and logs in again and the user account is updated.

  • Manually creating/uploading users and roles ahead of time avoids this situation.
    

•  Active Directory:
  • Customers using LDAP must ensure that the frevvo.User, frevvo.TenantAdmin and frevvo.Designer roles are specified on their LDAP/AD server. 
    
    • • All users requiring access to  must be assigned to the frevvo.User group. 
      • Tenant admin users must be assigned to the frevvo.User and frevvo.TenantAdmin groups,
      • Designer users must be assigned to the frevvo.User  and frevvo.Designer groups.
        
        

Configuring the SAML Security Manager

In the directions given below, the Service Provider refers to frevvo . The metadata for your SAML tenant must be obtained first. Customers will need to configure the metadata when creating the SAML tenant.

1. In-house Customers Only
   1. Generate Your Certificate
   2. Install the Java Cryptography Extension API
2. Create the frevvo Metadata file.
3. Configure your Identity Provider
4. Create/edit the SAML tenant
5. Manage Users/Roles for your SAML tenant
6. Logging into Live Forms in a SAML Tenant

Step 1 - In-house Customers Only

Cloud customers can skip the Generate Your Certificate and Install the Java Cryptography steps. These instructions are provided for On-premise customers only.

Generate Your Certificate

If you re using the frevvo tomcat bundle, the supplied keystore, frevvoKeystore.jks is located in the <frevvo-home>/tomcat/lib folder, The keystore contains a default certificate with alias=frevvo and password=p@ssw0rd. Replace this  with a certificate for your installation.

• The alias and password can be configured with the properties, com.frevvo.security.saml.key and com.frevvo.security.saml.password in the <frevvo-home>\tomcat\conf\localhost|frevvo.xml file.

This certificate is used to sign/encrypt the SAML request. The use of a long-lived self-signed certificate is recommended.

Since the keystore is located outside the frevvo war, you can use the Java keytool to generate and store your certificates. Folllow these steps:

1. Login as administrator.

2. Delete the existing certificate:

   Code Block
   keytool -delete -alias frevvo -keypass p@ssw0rd -keystore frevvoKeystore.jks -storepass p@ssw0rd

3. Generate a new certificate: Here is the command: Change the -dname value to the DNS name of your IDP

   Code Block
   keytool -genkey -dname "cn=app.frevvo.com" -alias frevvo -keypass p@ssw0rd -keystore frevvoKeystore.jks -storepass p@ssw0rd -keyalg rsa -keysize 2048 -validity 3650

4. The certificate can be viewed (and used in the metadata XML) by exporting it to a file:
   

   Code Block
   keytool -exportcert -alias frevvo -file frevvo.rfc -rfc -keystore frevvoKeystore.jks -storepass p@ssw0rd

Install the Java Cryptography Extension

The Java Cryptography Extension (JCE) provides a uniform framework for the implementation of security features in Java. These files are needed to avoid an i"llegal key size" error which can happen if these files are missing in the Java Development Kit (JDK) software of your on-premise installation.

Follow these steps to install the JCE files into the JDK:

1. Go to the Oracle Java SE download page http://www.oracle.com/technetwork/java/javase/downloads/index.html
2. Scroll down … Under "Additional Resources" section you will find "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File"
3. Download the version that matches your installed JVM  - for example, download UnlimitedJCEPolicyJDK8.zip if you are using JDK/JRE version 8
4. Unzip the downloaded zip. 
5. Copy local_policy.jar and US_export_policy.jar to the <JAVA_HOME>/jre/lib/security (Note: these jars are already there so you have to overwrite them)
6. Restart .

Step 2 - Create the Live Forms Metadata file

Follow these steps to generate the frevvo metadata for your 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 SAML tenant.

   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.
   
   Image Added
   
   

3. Save the page as an xml file.
4. Metadata must be generated for each SAML tenant. Each tenant will have a unique URL.

Step 3 - Configure Your Identity Provider

1. Configure the Service Provider metadata for your Identity Provider. For example, the Shiboleth Identity provider requires modification of a file to provide the path to the tenant metadata xml file created above.
2. Your Identity Provider must be configured to expose the attributes that requires. Attribute mapping is done when you create the SAML tenant. These are:
   1. User Id
   2. First Name
   3. Last Name
   4. Email
   5. Manager Id (optional)
   6. Groups
   7. Custom Attributes (optional)

We know that your IDP software of choice is outside of the frevvo server software and that you have the expertise in house to install, configure and maintain your IDP software. But here are some tips we have found that may assist you.

Step 4 - Create/edit the SAML tenant

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

  metadata file

• The metadata for your Identity Provider
• Attribute mapping information  

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

 Log onto as the superuser (on-premise) or the tenant admin (cloud).

1. Access the Add Tenant (on-premise) or Edit Tenant (cloud) screen.
2. Select SAML Security Manager from the Security Manager Class dropdown.
3. Copy the Service Provider (frevvo) metadata into the Service Provider field. The xml should be pasted without the prolog. For example, the image shows an example of the frevvo metadata file before pasting:
   
   
   
   
4. Retrieve the metadata for your Identity Provider. For example, for the Shiboleth product the metadata is located in the idp-metadata file.
   
   
5. Paste the metadata into the Identity Provider field. This metadata should also be pasted without the prolog.
   
   
   
   
6. 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. Refer to the Mixed or Upper case User Names topic for more information.

7. Check the Authentication Only checkbox if you want SAML to handle authentication and provide user identification but all other user attributes come from the  database.
   
   When checked, the screen display changes as attribute mapping, other than the mapping for the user id and custom attributes, is no longer necessary.
   
   Image Modified
   
   

   Note

   Authentication Only: If Authentication Only is checked: SAML will authenticate the user but not retrieve any of the attributes. Authorization depends on the roles defined in . Changes made in the UI will not be overridden if the user logs out and then logs in again. Manual creation of users & roles in the SAML tenant is required. This can be done with a csv upload. If Authentication Only is unchecked: All users requiring access to must be assigned to the frevvo.User group in Active Directory. Tenant Admins must be assigned to the frevvo.User and frevvo.TenantAdmin groups. Designer users must be assigned to the frevvo.User and frevvo.Designer groups. Users are added (discovered) when they log in.  It is important to know that a SAML tenant in this mode (SAML/LDAP handles authentication and authorization) that users and tenant admins can modify user information in the UI. If user information/role assignment is changed in the UI, the changes will be overwritten by the information in SAML the next time the user logs out and then logs back in again. In this case, make the changes in your Active Directory to make them permanent.

8. Map the attributes configured in your Identity Provider by entering the name for each attribute in the corresponding field on the screen. Be sure to provide the attribute name - not the friendly name. For example, if you are using Shibboleth for your Identity Provider the attribute information is located in the attribute-resolver.xml file. The image shows the section of the file where the attributes are defined.
   
   
   The image below shows the attribute mapping on the screen with the attribute names from the Shibboleth file:

   
   
   

   Note
   If Authentication Only mode is enabled for your tenant, mapping is only required for the User Id. Refer to step 8 for the details

9. Custom attributes can be mapped by typing the attribute names in the Custom field separated by a comma.
10. Configure a tenant admin account. This account  does not require SAML authentication. This tenant admin can log directly into 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 SAML login is used.
    
    
    
    The forgot password function works for a SAML tenant admin user. For all others, it will display the error message about not being supported for the tenant.
    
    
    
    
11. Configure the Business Calendar for your tenant and HTTP Authorization Credentials if required.
12. Click Submit.
    

...

SAML Tenant backdoor admin user

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

When you create a new tenant you are prompted to set up a tenant admin user id and password. If you are using a SAML IDP, this tenant admin does not authenticate via your SAML IDP. It only exists in . If you experience an issue with your SAML configuration such that you can't login as a 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 SAML configuration issue. Only one backdoor tenant admin account is supported.

Image Modified

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

• Using the Forgot Password? feature for the tenant admin account.
• Logging in as a 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. Make sure Authentication Only is unchecked in your SAML tenant.
2. Make sure the custom attribute(s) are configured in Active Directory and assigned to the correct users.

3. Configure and release the custom attributes as SAML attributes in your IDP.  

   Tip
   The procedure to expose custom attributes will differ depending on the IDP you have selected. Refer to your IDP documentation or your on-staff IDP expert to complete this step.

4. Map the attribute with this name in the Custom section of the tenant setup screen.
   1. You can do this when you are creating your SAML tenant or by accessing the Edit Tenant link, after signing on as the tenant admin of your existing SAML tenant.
5. Save the tenant configuration.
6. Write a business rule to populate controls in your form/flow with the information.
   

Example:

Let's take a look at a installation using a SAML tenant, Shibboleth as the IDP and Active Directory for authentication. When the user logs into the SAML tenant, you want to populate these fields in your form with the information from the LDAP server:

These attributes must be configured and released in your IDP. The process to expose the attributes varies for each Identity Provider. In our example, which uses the Shibboleth IDP, configuration and release of the attributes is done in two files, attribute-resolver.xml and attribute-filter.xml. You may need to confer with your on-staff IDP expert to complete this step.

...