Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column

Frevvoproduct
supports the creation of a tenant using the SAML (Security Assertion Markup Language) Security Manager. Users in this tenant can log into
Frevvoproduct
via  (SAML) version 2.0. SAML enables internet single sign-on by allowing users to authenticate at an identity provider and then access service providers without additional authentication.

The SAML Security manager can be used in on-premise installations but it is primarily meant for cloud tenants who use LDAP but do not want to expose it over the internet.

SAML requires the configuration and installation of an identify provider that supports SAML 2.0. Some examples are Google, Shibboleth, OpenSSO, ADFS, and PingFederate, OneLogin.

In a SAMLenvironment, integration with an LDAP server for authentication is common. In general, here's how it works:

  • User A attempts to access Live forms by typing the URL into the browser
  • Live forms sends a SAML request for authentication to the Identity Provider
  • The Identity Provider requires more information. The Identify Provider login screen is displayed.
  • User A logs into the Identity Provider.
  • The Identity Provider may communicate with your LDAP server if you are using Active Directory for authentication.
  • The Identity Provider builds and sends a SAML token to Live Forms containing the security information for User A.
  • Live forms processes the information. If User A has been authenticated, Live forms establishes a session and redirects User A to the correct Live Forms screen depending on User A's authorization level.
Column
width400px

On this page:

Table of Contents
maxLevel2

...

Info

frevvo only supports/certifies the SAML Security Manager when

Frevvoproduct
is running in the tomcat container. Refer to our Supported Platforms for the list of Application Servers supported/certified by frevvo.

...

    • 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 

        Frevvoproduct
        . The user then gets promoted to manager. The user will not receive a task routed to the user's new role of manager if the. 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 
          Frevvoproduct
           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.

Warning
  • The group names for these three special roles must be frevvo.User, frevvo.TenantAdmin, and frevvo.Designer. Upper/lower case may be a factor for Open LDAP systems.
  • frevvo Best Practice recommends that you create a user account in your Active Directory or IDP that will house all of your deployed Production forms/flows. This user can be named anything i.e.frevvoProduction but it must be a member of the frevvo.Designer group.
  • If you want to preserve Applications/Forms/flows developed in your trial/starter tenant, download them to your desktop as a backup then delete the user account BEFORE changing the Security Manager.
  • frevvo only supports the SAML Security Manager when
    Frevvoproduct
    is running in the tomcat container. Refer to our Supported Platforms for the list of Application Servers supported/certified by frevvo.

...

In the directions given below, the Service Provider refers to frevvo

Frevvoproduct
. The metadata for your
Frevvoproduct
SAML tenant must be obtained first. Customers will need to configure the
Frevvoproduct
metadata when creating the SAML tenant.

  1. Create the frevvo Metadata file.
  2. Configure your Identity Provider
  3. Create/edit the SAML tenant
  4. Manage Users/Roles for your SAML tenant
  5. Logging into Live Forms in a SAML Tenant

Section 1 - In-house Customers Only

...

  1. Stop
    Frevvoproduct
    if it is running.
  2. Copy the default <frevvo-home>\tomcat\lib\ frevvoKeystore.jks to another location as a backup
  3. Login as administrator.
  4. Make sure the path to the keytool application is configured in your system path. keytool is part of the standard Java distribution (JDK or JRE)). For example, keytool is located in the C:\Program Files\Java\jdk1jdkx.8x.0_92x\bin directory in the Java 8 JDK.
  5. Navigate to <frevvo-home>\ tomcat\lib or to the new location of the keystore if you changed the com.frevvo.security.saml.keystore property in the setenv or service.bat files
  6. Delete the existing certificate:

    Code Block
    keytool -delete -alias frevvo -keypass p@ssw0rd -keystore frevvoKeystore.jks -storepass p@ssw0rd
  7. If you changed the password from the default, execute this keytool command to change the password in the keystore

    Code Block
    keytool -storepasswd -keystore frevvoKeystore.jks - it will ask for the old password - p@ssw0rd and then prompt for the new one - The keystore password must match whatever is in the line that we added to the setenv pr service.bat files.
  8. Generate a new certificate: Here is the command: Change the -dname value to the DNS name of your IDP.

    If you changed the values of the com.frevvo.security.saml.key or com.frevvo.security.saml.password properties in the setenv or service.bat files then change the alias in the command and the keypass and storepass password parameters to match those values. The key and store passwords need to be the same as there is only one password property.

    The dname in this keytool command specifies the X.500 Distinguished Name to be associated with the alias and is used as the issuer and subject fields in the self-signed certificate. While we provide a sample in the documentation, it is up to the customer (your security policy) to decide what the value should be when the certificate.for your installation is generated. Since this is a self-signed certificate - the dname really could be anything - but here is a link to the Oracle documentation to give you some idea of what you might want to set that too.

    Execute this command to create a new certificate and stores it in the keystore.

    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


  9. The certificate can be viewed by exporting it to a file. If you changed the password, substitute the new password in the command:

    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 "illegal key size" error which can happen if these files are missing in the Java Development Kit (JDK) software of your on-premise installation.

Determine the version of the Java 8 JDK that you are running by typing java -version in a command window

  • If you are using a version of the JDK 8 u161+ , you can skip this step.The correct jar files are already included in the JDK.
  • For versions of the JDK 8 previous to u161, follow these steps to install the JCE files into the JDK:
    1. Go to the Oracle Java SE download page. 
    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 <JAVA_HOME>/jre/lib/security (Note: these jars are already there so you have to overwrite them)
    6. Restart 
      Frevvoproduct
      .

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

...

Section 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
    Frevvoproduct
    tenant metadata xml file created above.
  2. Your Identity Provider must be configured to expose the attributes that
    Frevvoproduct
    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)

...

titleClick here for some tips when configuring ADFS
Warning

The information below applies to ADFS v2.0. If you are using a different version, your ADFS expert must locate the equivalent functions for that version.

...

Save the frevvo tenant metadata as an xml file. Add Relying Party Metadata Trust. Use the 'Import data about the relying party from a file' option to upload the saved xml file.

...

In Edit Claim Rules, create a rule to map AD attributes to the outgoing claim type as shown below.  Information about creating rules to send LDAP attributes as Claims can be found on this Microsoft support website

  1. samAccountName to NameID - If you rather generate an opaque identifier, you would need to create custom rules as described here.
  2. samAccountName to Windows Account Name
  3. givenName to Given Name
  4. Surname to Surname
  5. emailAddresses to Email Address
  6. Group membership is added using the wizard. Select Token-Groups Unqualified Names and map it to the Group claim.

Extract the Manager's samAccountName. This can be done using the following 3 custom claim rules. This rule assumes that the CN of the manager DN contains the samAccountName:

...

Section 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 browser:

    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.

Section 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
    Frevvoproduct
    tenant metadata xml file created above.
  2. Your Identity Provider must be configured to expose the attributes that
    Frevvoproduct
    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.

Expand
titleClick here for some tips when configuring ADFS
Warning

The information below applies to ADFS v2.0. If you are using a different version, your ADFS expert must locate the equivalent functions for that version.

  1. Save the frevvo tenant metadata as an xml file. Add Relying Party Metadata Trust. Use the 'Import data about the relying party from a file' option to upload the saved xml file.

  2. In Edit Claim Rules, create a rule to map AD attributes to the outgoing claim type as shown below.  Information about creating rules to send LDAP attributes as Claims can be found on this Microsoft support website

    1. samAccountName to NameID - If you rather generate an opaque identifier, you would need to create custom rules as described here.
    2. samAccountName to Windows Account Name
    3. givenName to Given Name
    4. Surname to Surname
    5. emailAddresses to Email Address
    6. Group membership is added using the wizard. Select Token-Groups Unqualified Names and map it to the Group claim.

  3. Extract the Manager's samAccountName. This can be done using the following 3 custom claim rules. This rule assumes that the CN of the manager DN contains the samAccountName:

    Code Block
    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=", ""));
  4. In the

    Frevvoproduct
    tenant, map the attributes as shown: Refer to this website for more information about Claims.
     

    AttributeValue
    User Idhttp://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

    First Name 

    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    Last Namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    Emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    Manager User Idhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/manageraccountname
    Roleshttp://schemas.xmlsoap.org/claims/Group
  5. It is recommended that you turn on tracing in ADFS, so that the SAML response is visible. Compare the names of the attributes contained in the response to the names of the attributes configured on the tenant screen. If turning on ADFS tracing is not an option, the frevvo log can be searched for the name attribute values.

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:

  1. Make sure the custom attribute, in our example StaffID, is configured in Active Directory and assigned to the correct users.
  2. Expose StaffID as a SAML attribute by writing an ADFS claim rule.
    1. During this process, you assign the attribute a name, e.g. 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 == "
    1. staffid
  3. Map the attribute with this name in the Custom section of the tenant setup screen. Save the tenant configuration.

    Image Added

  4. Here is an example of a business rule that references the custom attribute, Staff Id, and populates a field in a form named StaffID.

    Code Block
    if (form.load) {
      StaffID.value =  _data.getParameter('subject.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=", ""));
  5. In the

    Frevvoproduct
    tenant, map the attributes as shown: Refer to this website for more information about Claims.
     

    AttributeValue
    User Idhttp://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

    First Name 

    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    Last Namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
    Emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    Manager User Idhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/manageraccountname
    Roleshttp://schemas.xmlsoap.org/claims/Group
  6. It is recommended that you turn on tracing in ADFS, so that the SAML response is visible. Compare the names of the attributes contained in the response to the names of the attributes configured on the tenant screen. If turning on ADFS tracing is not an option, the frevvo log can be searched for the name attribute values.

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:

  • Make sure the custom attribute, in our example StaffID, is configured in Active Directory and assigned to the correct users.
  • Expose StaffID as a SAML attribute by writing an ADFS claim rule.
    1. During this process, you assign the attribute a name, e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/staffid
  • Map the attribute with this name in the Custom section of the tenant setup screen. Save the tenant configuration.
    Image Removed
    Here is an example of a business rule that references the custom attribute, Staff Id, and populates a field in a form named StaffID.
    Code Block
    if (form.load) {
      StaffID.value =  _data.getParameter('subject.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/staffid');
    }
    Refer to Retrieving Custom Attributes from LDAP in a SAML Tenant for another example.
    Expand
    titleClick here for instructions to configure Google Apps as the SAML IDP

    Follow these steps to setup Google as the Identity Provider and Live Forms as the Service Provider to configure Single Sign On. These instructions are for Cloud. On-Premise customers follow the same steps with one additional step to generate a certificate:

    1. On - Premise customers ONLY: Generate a certificate. 
    2. Configure Google as the Identity Provider
    3. Login to your Google domain as an admin, go to the admin portal and click through to Apps > SAML Apps. If you have any existing SAML apps, you’ll see them here. Click the big PLUS (+) sign at bottom right to add a new one. A wizard will appear.
    4. Click the “Setup My Own Custom App” link at the bottom of the screen.
      Image Removed
      Choose Option 2 and Download the IDP metadata file.
      Image Removed
      Provide a name for your application, a description and a logo.
      Image Removed
      Enter the Service Provider (
      Frevvoproduct
      ) details.For ACS URL, type 
      staffid');
      }


      Refer to Retrieving Custom Attributes from LDAP in a SAML Tenant for another example.

    Expand
    titleClick here for instructions to configure Google Apps as the SAML IDP

    Follow these steps to setup Google as the Identity Provider and Live Forms as the Service Provider to configure Single Sign On. These instructions are for Cloud. On-Premise customers follow the same steps with one additional step to generate a certificate:

    ...

    Tip

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

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

    ...

    Tip

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

    Session Timeout

    Session timeouts are configured in

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

    Embedding Forms/Flows in your website

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

    Info
    Embedding forms and flows into your website is NOT supported if the the visibility of the form is set to Public in Tenant and the user is NOT already authenticated to 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
    1. On - Premise customers ONLY: Generate a certificate. 
    2. Configure Google as the Identity Provider
      1. Login to your Google domain as an admin, go to the admin portal and click through to Apps > SAML Apps. If you have any existing SAML apps, you’ll see them here. Click the big PLUS (+) sign at bottom right to add a new one. A wizard will appear.
      2. Click the “Setup My Own Custom App” link at the bottom of the screen.

        Image Added

      3. Choose Option 2 and Download the IDP metadata file.

        Image Added

      4. Provide a name for your application, a description and a logo.

        Image Added

      5. Enter the Service Provider (
        Frevvoproduct
        ) details.
        1. For ACS URL, type https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/{tenant} - replace {tenant} with your cloud tenant.
        2. For Entity Id, type https://app.frevvo.com:443/frevvo/web/alias/{tenant} - replace {tenant} with your cloud tenant.
           
        For example, https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/ashish-saml.com
      6. Leave the built-in Name Id attribute configuration alone.

        Image Added

      7. Add a new Attribute Mapping: User Id | Basic Information | Primary Email

        Image Added

      8. Click Finish. The Setup Complete screen displays.
      9. Click OK.
      10. Your new SAML App will be displayed. Click the three dots at right and turn ON SSO. You can choose to turn it ON for everyone in your domain or for specific sub-domains.

        Image Added

    3. Create users in Google:
      1. Create your users in Google or move existing users into the appropriate sub-organization if you are limiting access to your SAML app in Google. You won’t have to create new users or move existing users if you enabled the SAML app for everyone in your Google domain.
      2. You’ll need a user in your Google domain to serve as the tenant administrator. Either, create a new one or choose an existing one (there’s nothing to do as long as you choose someone).
    4. Create users in
      Frevvoproduct
      :
      1. You need to ensure that the user you chose/created as the tenant admin exists in frevvo. Once we switch over to SAML, all authentication will use Google Apps credentials and you won’t be able to login using your current tenant admin or other users. We’ll use CSV upload. The file syntax looks like this:

        Code Block
        userId,tenant,firstName,lastName,email,enabled,reportsTo,roles,transaction
         {user}@{domain},{tenant},123,{first},{last},{email},true,,frevvo.Designer|frevvo.TenantAdmin,

        The fields are your Google login (e.g. prajakta.deshmukh@frevvo.com), your frevvo tenant id (e.g. ashish-saml.com), the first name, last name and email address. In the roles field, use the roles indicated above.

      2. Login as the current tenant admin user.
      3. Click on Manage Users.
      4. Click on Download CSV users file.
      5. Edit the file to setup at least one Google User (the one you chose/created as the tenant admin).
      6. Click on CSV Upload (the Excel looking icon) and upload the file to create this user.

    5. Configure 
      Frevvoproduct
      as the Service Provider:
      Create users in
      Frevvoproduct
      :
    6. You need to ensure that the user you chose/created as the tenant admin exists in frevvo. Once we switch over to SAML, all authentication will use Google Apps credentials and you won’t be able to login using your current tenant admin or other users. We’ll use CSV upload. The file syntax looks like this:

      Code Block
      userId,tenant,password,firstName,lastName,email,enabled,reportsTo,roles,transaction
       {user}@{domain},{tenant},123,{first},{last},{email},true,,frevvo.Designer|frevvo.TenantAdmin,

      The fields are your Google login (e.g. prajakta.deshmukh@frevvo.com), your frevvo tenant id (e.g. ashish-saml.com), any password (it is not used), the first name, last name and email address. In the roles field, use the roles indicated above.

    7. Login as the current tenant admin user.
    8. Click on Manage Users.
    9. Click on Download CSV users file.
    10. Edit the file to setup at least one Google User (the one you chose/created as the tenant admin).
    11. Click on CSV Upload (the Excel looking icon) and upload the file to create this user.
      Configure 
      Frevvoproduct
      as the Service Provider:
      1. Generate the SP metadata file from frevvo. Visit the URL: https://app.frevvo.com:443/frevvo/web/saml/SSOmetadata/alias/{tenant} - replace {tenant} with your cloud tenant.For Entity Id, type https://app.frevvo.com:443/frevvo/web/alias/{tenant} - replace in your browser. Replace {tenant} with your cloud tenant.
         For example, https://app.frevvo.com:443/frevvo/web/saml/SSO/alias/ashish-saml.comLeave the built-in Name Id attribute configuration alone.
        Image Removed
        Add a new Attribute Mapping: User Id | Basic Information | Primary Email
        Image Removed
      2. Click Finish. The Setup Complete screen displays.
      3. Click OK.
      4. Your new SAML App will be displayed. Click the three dots at right and turn ON SSO. You can choose to turn it ON for everyone in your domain or for specific sub-domains.
        Image Removed
    12. Create users in Google:
      1. Create your users in Google or move existing users into the appropriate sub-organization if you are limiting access to your SAML app in Google. You won’t have to create new users or move existing users if you enabled the SAML app for everyone in your Google domain.
      2. You’ll need a user in your Google domain to serve as the tenant administrator. Either, create a new one or choose an existing one (there’s nothing to do as long as you choose someone).
      1. Generate the SP metadata file from frevvo. Visit the URL: Right click to View Page Source and save as an XML file.
      2. Login to your Cloud account as tenant admin and click the Edit Tenant button.
      3. In the Security Manager section, click the Change button, choose SAML in the drop down that appears and click Ok. NOTE: Free Trial accounts do not show the Change button. If the Change button is not visible in your tenant, please contact customer support.
      4. The SAML configuration section will appear. In the Service Provider section, we must paste the SP metadata file we generated in Step 1 above. Unfortunately, the file contains an XML prolog (highlighted in the image below) which must be removed. Paste the contents of this SP metadata file without the prolog into the Service Provider text area of the configuration form.
      5. In the Identity Provider section, paste the IDP metadata file we generated and saved in the Google setup above. Once again, the file contains an XML prolog. Paste the contents of this IDP metadata file without the prolog into the Identity Provider text area of the configuration form.
      6. Check Authentication Only. This means SAML will authenticate the user but not retrieve any of the attributes. Users are not automatically discovered upon first login. Therefore, you must create users & roles using CSV upload.
        • If you do not wish to select the Authentication Only option, you’ll need to map other attributes in Google first before you can assign them in Frevvo. First Name, Last Name, and Email should be pretty straight forward since these attributes are surfaced by the Google SAML IdP app. The other attributes may be more difficult.
      7. With the Authentication Only option, attribute mapping only includes one attribute, the User Id. Since we mapped the email address to the User Id attribute in Google while setting up the SAML app, we can simply map the frevvo attribute to User Id in the configuration form.
      8. Submit the form and we’re done.

        Section
        Column
        width25%

        Image Added

        Edit tenant.

        Column
        width25%


        Image Added

        Setup SAML

        Column
        width25%


        Image Added

        SP Metadata (paste without XML Prolog)

        Column
        width25%

        Image Added

        IDP Metadata (paste without XML prolog)

    13. How to use your new SAML tenant
      1. Logout of all your Google accounts to test.
      2. Go to the tenant URL: https://app.frevvo.com:443/frevvo/web/saml/metadata/aliastn/{tenant} in your browser/login. Replace {tenant} with your cloud tenant . Right click to View Page Source and save as an XML fileid.
      3. You will be redirected to the Google login page.
      4. Login to your Cloud account as tenant admin and click the Edit Tenant button.
      5. In the Security Manager section, click the Change button, choose SAML in the drop down that appears and click Ok. NOTE: Free Trial accounts do not show the Change button. If the Change button is not visible in your tenant, please contact customer support.
      6. The SAML configuration section will appear. In the Service Provider section, we must paste the SP metadata file we generated in Step 1 above. Unfortunately, the file contains an XML prolog (highlighted in the image below) which must be removed. Paste the contents of this SP metadata file without the prolog into the Service Provider text area of the configuration form.
      7. In the Identity Provider section, paste the IDP metadata file we generated and saved in the Google setup above. Once again, the file contains an XML prolog. Paste the contents of this IDP metadata file without the prolog into the Identity Provider text area of the configuration form.
      8. Check Authentication Only. This means SAML will authenticate the user but not retrieve any of the attributes. Users are not automatically discovered upon first login. Therefore, you must create users & roles using CSV upload.
        • If you do not wish to select the Authentication Only option, you’ll need to map other attributes in Google first before you can assign them in Frevvo. First Name, Last Name, and Email should be pretty straight forward since these attributes are surfaced by the Google SAML IdP app. The other attributes may be more difficult.
      9. With the Authentication Only option, attribute mapping only includes one attribute, the User Id. Since we mapped the email address to the User Id attribute in Google while setting up the SAML app, we can simply map the frevvo attribute to User Id in the configuration form.
      10. Submit the form and we’re done.
    Section
    Column
    width25%

    Image Removed

    Edit tenant.

    Column
    width25%
    Image Removed

    Setup SAML

    Column
    width25%
    Image Removed

    SP Metadata (paste without XML Prolog)

    Column
    width25%

    Image Removed

    IDP Metadata (paste without XML prolog)

    How to use your new SAML tenant
    1. Logout of all your Google accounts to test.
    2. Go to the tenant URL: https://app.frevvo.com:443/frevvo/web/tn/{tenant}/login. Replace {tenant} with your tenant id.
    3. You will be redirected to the Google login page.
    4. Login to Google as the Google user you chose/created as the tenant admin.
    5. You will be redirected to frevvo to the Manage Tenant screen.

    The user id displayed in frevvo at the top will look like {user}@{domain}@{tenant} which is a bit confusing but is purely cosmetic.

    Image Removed
  • Load other users in frevvo

    Before your other Google users can login to 

    Frevvoproduct
    using their Google Apps credentials, they must first be created in frevvo. You can download users from Google Apps as a CSV file (uncheck the create a Google Sheet option), modify it to follow frevvo’s syntax as shown above and upload it. You can also login as the tenant admin Google user and create users and roles using the UI.

    Once the user exists in frevvo, he/she can login using Google credentials and the system will behave as expected according to the roles assigned to the user.

  • Section 4 - Create or edit the SAML tenant

    To successfully create a

    Frevvoproduct
    tenant using the SAML Security manager, you will need the following:

     

    Frevvoproduct
    metadata file

    • The metadata for your Identity Provider
    • Attribute mapping information  

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

     Log onto

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

    ...

    Frevvoproduct

    ...

    Frevvoproduct

    ...

    Authentication Only:

    ...

    Frevvoproduct

    ...

    Frevvoproduct

    ...

    Frevvoproduct

    ...

    • All users requiring access to

      Frevvoproduct
      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
      Frevvoproduct
      UI. If user information/role assignment is changed in the
      Frevvoproduct
      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.

    ...

    Frevvoproduct

    ...

    Frevvoproduct

    ...

    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

    ...

    Frevvoproduct

    ...

    1. The tenant admin id, password and email fields are required. The Change password on next login field is optional. It is checked by default.
    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.

    ...

    Section 5 - Users and Roles in a SAML tenant

    Choosing the Authentication only option in your SAML tenant implies that the user and roles will be managed from 

    Frevvoproduct
    . You may choose this mode if:

      1. You do not want to add 
        Frevvoproduct
         roles to your LDAP.
      1. LDAP has many roles that have no relevance to your workflow.
      2. Find the SAML mapping for the other required attributes complex. For some IDPs, retrieving the manager user id and role names may require writing custom rules.

    When Authentication Only is selected (checked) there is no discovery of Users & Roles. They must be created in your tenant manually. The CSV upload is a good way to do this.

    When Authentication Only is not selected (unchecked) 

    Frevvoproduct
     will discover new users at run-time. However users are only discovered when the person tries to login. They are not discovered nor is their user data (email, name, report-to) kept in sync automatically. It requires the user to login. So, this does not necessarily remove the need for manually creating/uploading users and roles ahead of time nor does it remove the need to continuously update the users when changes are made in LDAP. 

    If you have workflows that are routed to users/roles there is no guarantee that the required users will login before a task is created for that user (specifically or via a role). For example, if  a workflow is routed to a specific user and it is performed before the first login of that user, 

    Frevvoproduct
     will send an email to the tenant admin indicating that the user is unknown. Routing based on the user's manager will fail. Routing based on a role will succeed but the user will receive no notification.

    Manually creating/uploading users/roles in 

    Frevvoproduct
     ahead of time avoids this situation. 

    Warning

    It is important to know that a SAML tenant with Authentication Only unchecked, means that authentication and authorization are handled by SAML/LDAP. Users are added/updated through discovery. If a tenant admin modifies user information in the

    Frevvoproduct
    UI, for example, changes an email address or adds a role for a user, the changes will stay in effect until the user logs out of the tenant and then logs back in. When the user logs back in, the changes made in the
    Frevvoproduct
    UI will be overwritten by the information in SAML/LDAP. In this case, make the changes in your Active Directory to make them permanent. A warning message will appear on the User List to alert the admin that they are in discovery mode and should make permanent changes in their IDP instead.

    Image Removed

    Section 6 - Logging into a Live Forms SAML Tenant

    1. Paste this URL into your browser:
      1. Cloud Customers: https://app.frevvo.com:443/frevvo/web/tn/{t}/login - Replace {t} with the name of your 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 SAML tenant.
    2. Frevvoproduct
      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.

    This URL redirects to /web/saml/login/alias/{t}. This initiates the SAML authentication process by redirecting to the Identity Provider login page.  If the user is authenticated, the rest of the standard login processing is done (verify license, redirect on success etc).

    Note
    • Clicking the logout link in
      Frevvoproduct
      , logs the user out from
      Frevvoproduct
      only.
    • Accessing a Space in a SAML tenant on a mobile device will not display a logout button.
    • When a user logs in to Live Forms (non-space mode), the logout link will be visible
    • Cloud customers browsing app.frevvo.com or in-house customers browsing  http://<servername>:<port>/frevvo/web/login attempting to log into a SAML tenant directly (user@saml tenant name) will automatically be redirected to the SAML IDP login page.

    SAML Tenant backdoor admin user

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

    ...

    Browse this URL to login as the Backdoor Admin: <base_URL>/frevvo/web/admin/login The base URL is an Application Property. When specified,

    Frevvoproduct
    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 backdoor admin.
    • Non admin users can also login using the admin specific URL.

    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:

    ...

      1. Google as the Google user you chose/created as the tenant admin.
      2. You will be redirected to frevvo to the Manage Tenant screen.

      The user id displayed in frevvo at the top will look like {user}@{domain}@{tenant} which is a bit confusing but is purely cosmetic.


      Image Added

    1. Load other users in frevvo

      Before your other Google users can login to 

      Frevvoproduct
      using their Google Apps credentials, they must first be created in frevvo. You can download users from Google Apps as a CSV file (uncheck the create a Google Sheet option), modify it to follow frevvo’s syntax as shown above and upload it. You can also login as the tenant admin Google user and create users and roles using the UI.

      Once the user exists in frevvo, he/she can login using Google credentials and the system will behave as expected according to the roles assigned to the user.

    Section 4 - Create or edit the SAML tenant

    To successfully create a

    Frevvoproduct
    tenant using the SAML Security manager, you will need the following:

     

    Frevvoproduct
    metadata file

    • The metadata for your Identity Provider
    • Attribute mapping information  

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

     Log onto

    Frevvoproduct
    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:

      Image Added

    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.

      Image Added

    6. Check the Ignore Case checkbox if you are using LDAP for authentication and you want
      Frevvoproduct
      to ignore the case stored in LDAP systems for users/roles. It is checked by default. 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

      Frevvoproduct
       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 Added

      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 
          Frevvoproduct
          . Changes made in the
          Frevvoproduct
          UI will not be overridden if the user logs out and then logs in again.
        • Manual creation of users & roles in the
          Frevvoproduct
          SAML tenant is required. This can be done with a csv upload.

      • If Authentication Only is unchecked:
        • All users requiring access to

          Frevvoproduct
          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
          Frevvoproduct
          UI. If user information/role assignment is changed in the
          Frevvoproduct
          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

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

      Image Added
      The image below shows the attribute mapping on the
      Frevvoproduct
      screen with the attribute names from the Shibboleth file:

      Image Added

      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
      Frevvoproduct
      providing a default security manager built-in admin.

      1. The tenant admin id, password and email fields are required. The Change password on next login field is optional. It is checked by default.
      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. For cloud customers the <base> is always https://app.frevvo.com.
      3. If the tenant based login url is used i.e. /frevvo/web/tn/{t}/login then SAML login is used. 

      Image Added

      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.

      Image Added

    11. Configure the Business Calendar for your tenant and HTTP Authorization Credentials if required.
    12. Click Submit.

    Section 5 - Users and Roles in a SAML tenant

    Choosing the Authentication only option in your SAML tenant implies that the user and roles will be managed from 

    Frevvoproduct
    . You may choose this mode if:

      1. You do not want to add 
        Frevvoproduct
         roles to your LDAP.
      1. LDAP has many roles that have no relevance to your workflow.
      2. Find the SAML mapping for the other required attributes complex. For some IDPs, retrieving the manager user id and role names may require writing custom rules.

    When Authentication Only is selected (checked) there is no discovery of Users & Roles. They must be created in your tenant manually. The CSV upload is a good way to do this.

    When Authentication Only is not selected (unchecked) 

    Frevvoproduct
     will discover new users at run-time. However users are only discovered when the person tries to login. They are not discovered nor is their user data (email, name, report-to) kept in sync automatically. It requires the user to login. So, this does not necessarily remove the need for manually creating/uploading users and roles ahead of time nor does it remove the need to continuously update the users when changes are made in LDAP. 

    If you have workflows that are routed to users/roles there is no guarantee that the required users will login before a task is created for that user (specifically or via a role). For example, if  a workflow is routed to a specific user and it is performed before the first login of that user, 

    Frevvoproduct
     will send an email to the tenant admin indicating that the user is unknown. Routing based on the user's manager will fail. Routing based on a role will succeed but the user will receive no notification.

    Manually creating/uploading users/roles in 

    Frevvoproduct
     ahead of time avoids this situation. 

    Warning

    It is important to know that a SAML tenant with Authentication Only unchecked, means that authentication and authorization are handled by SAML/LDAP. Users are added/updated through discovery. If a tenant admin modifies user information in the

    Frevvoproduct
    UI, for example, changes an email address or adds a role for a user, the changes will stay in effect until the user logs out of the tenant and then logs back in. When the user logs back in, the changes made in the
    Frevvoproduct
    UI will be overwritten by the information in SAML/LDAP. In this case, make the changes in your Active Directory to make them permanent. A warning message will appear on the User List to alert the admin that they are in discovery mode and should make permanent changes in their IDP instead.

    Image Added

    Discovery updates only occur when the user logs into the tenant. The admin "login as" feature will not execute a discovery update.

    Section 6 - Logging into a Live Forms SAML Tenant

    Browse the URL below to initiate the SAML authentication process by redirecting to the Identity Provider login page.  

    • Cloud Customers: https://app.frevvo.com:443/frevvo/web/tn/{t}/login. Replace {t} with the name of your 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 SAML tenant.
    Note
    • Clicking the logout link in
      Frevvoproduct
      , logs the user out from
      Frevvoproduct
      only.
    • Accessing a Space in a SAML tenant on a mobile device will not display a logout button.
    • When a user logs in to Live Forms (non-space mode), the logout link will be visible
    • Cloud customers browsing app.frevvo.com or in-house customers browsing http://<servername>:<port>/frevvo/web/login attempting to log into a SAML tenant directly (user@saml tenant name) will automatically be redirected to the SAML IDP login page. For best performance, frevvo recommends using the login URL described above.
    Warning

    sameSiteCookies attribute

    Please see this documentation on the use of the sameSiteCookies attribute to ensure compatibility with your SAML configuration.

    SAML Tenant Built-in Admin User

    Just a reminder that the tenant admin account can login directly into Live Forms or use the 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 SAML IDP. It only exists in Live Forms. If you experience an issue with your SAML configuration such that you can't login as an SAML authenticated user, use this this account to login to your tenant as a tenant admin in order to fix your SAML configuration issue. Only one built-in tenant admin account is supported.

    Image Added

    Browse this URL to login as the built-in admin: <base_URL>/frevvo/web/admin/login. When specified,

    Frevvoproduct
    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 login using the admin specific URL.

    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:

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

      Image Added

    • Logging in as a SAML authenticated tenant admin and changing the password via Manage Users.
    Tip

    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:

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

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

    Logged in User Display in Azure SAML Live Forms tenant

    If your SAML userIds are in the format <username>@<domain name>, when you login to 

    Frevvoproduct
    the
    Frevvoproduct
    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
    Frevvoproduct
    tenant name, it will appear as if the domain name is listed twice.

    Image Added

    Session Timeout

    Session timeouts are configured in

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

    Embedding Forms/Flows in your website

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

    Info

    Embedding forms and workflows into your website (and other use of the Link (Email/Webpage) share URL) is NOT supported if the the visibility of the form is set to Public in Tenant and the user is NOT already authenticated to 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. Users will see an error like this one if you open your browser's console:

    Refused to display 'https://....' in a frame because it set 'X-Frame-Options' to 'deny'.

    Tip

    If the tenant is using a SAML security manager, always use the Raw form link (see this documentation) to access your forms. This link will not load the form in a frame and login will work as expected. 

    If you are embedding your forms inside another website, then make certain that user has to login to IDP before they can see that web page. If the user is already logged in, the form will load correctly (even inside a frame).

    Automating the Daily CSV Upload

    ...

    Login fails with illegal Key Size Error

    After a failed login, ithis if this error message appears in the <frevvo-home>\tomcat\logs\frevvo.log file:

    ...

    This error indicates the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are missing in the Java Development Kit (JDK) software of your on-premise installation. Follow the steps above for the solution.Esnure you have the support version of JDK installed which includes the JCE. 

    The IDP login page does not display in the Microsoft Edge Browser

    ...