Versions Compared

Key

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

...

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

...

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/staffid
  3. Map the attribute with this name in the Custom section of the tenant setup screen. Save the tenant configuration.



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



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



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



    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.



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



    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.



  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:
    1. Generate the SP metadata file from frevvo. Visit the URL: https://app.frevvo.com:443/frevvo/web/saml/metadata/alias/{tenant} in your browser. Replace {tenant} with your cloud tenant. 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%

      Edit tenant.


      Column
      width25%


      Setup SAML


      Column
      width25%


      SP Metadata (paste without XML Prolog)


      Column
      width25%

      IDP Metadata (paste without XML prolog)



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




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

...

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  

...

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



    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.


    The image below shows the attribute mapping on the
    Frevvoproduct
    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
    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. 



    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.

...

Info

Embedding forms and flows 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

...