Live Forms Latest - This documentation is for Live Forms 9.0. Not for you? Earlier documentation is available too.

Versions Compared

Key

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

...

  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\jdkx.x.x\bin directory in the 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

...

  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 backdoorbuilt-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 Modified

    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 Modified

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

...

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

...

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 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 built-in tenant admin account is supported.


Browse this URL to login as the Backdoor Adminbuilt-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 backdoor adminbuilt-in.
  • Non admin users can also login using the admin specific URL.

...

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



  • Logging in as 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 Backdoor Admin built-in userid from the Edit Tenant page.

...

Tip

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

...