NEW ZenQMS SSO Single Sign-On Self Service

 

We are happy to offer our ZenQMS Single Sign-On Self Service. This feature will allow you to configure your own single sign-on solution with the ability to enable and disable the feature at your own convenience. ZenQMS supports SAML 2.0 for Single Sign-On (SSO), including defined gallery entries for various SSO Identity Providers (e.g. Azure AD, Okta, OneLogin).

Recommendation Read the entirety of this article before proceeding. Always configure and test in your Sandbox environment before implementing in Production. 

Table of Contents

Enabling a User to Configure SSO

The first step in this process is to ensure your user has the permission to access the Single Sign-On (SSO) section of the Settings module. An Account Super User will need to add you to a Role with the "Account Single Sign-On (SSO)" permission enabled. 

  • Navigate to your target environment (app.zenqms.com or sandbox.zenqms.com).
  • Navigate to the Settings module.

Settings_module.png

  • Navigate to Settings > Account > Roles/Permissions

roles_permissions.png

  • Create a role with the "Account Single Sign-On (SSO)" permission box checked/enabled. Or add this permission to an existing role. Select the "Create Role" button to create a role. 

sso_admin_permisison.png

The "Account Single Sign-On (SSO)" permission will allow users to configure your SSO solution within the target environment. 

Configuring or Editing your Single Sign-On Solution 

Now that you have enabled your user by adding the appropriate "Account Single Sign-On (SSO)" permission to a role, you may start configuring or managing your SSO solution. 

  • Navigate to your target environment (app.zenqms.com or sandbox.zenqms.com).
  • Navigate to the Settings module.
  • Navigate to Settings > Account > Single Sign-On (SSO).

sso_settings.png

Once the user has access to the SSO Self Service, they will see a "Create" button and a basic table with a list of configurations, or an empty table if no configuration has been created.

The columns in the table are:

  • Provider: the provider selected to a configuration
  • Domains: the domains added to a configuration
  • Created: when the configuration was created
  • Expires: when the configuration is going to expire
  • Enabled: the activation state of a configuration

 

SSO_Table.png

 

The following information is required to configure your SSO:

  • SSO Provider
  • Entity ID
  • Single Sign-On Service URL
  • X.509 Certificate
  • Email Attribute
  • Select How Users Will Execute Signatures

Users can click on the Create button or on the Provider name to open the slider with an empty form or the current configuration details. The fields available at a first glance are:

  • Provider: the configuration provider. Can be selected from existing ones or set as "Other" in case it's not in the list.
  • Entity ID: a name for the configuration in the form of a URL. The URL doesn't have to locate a resource but it's common for it to point to the home page of the web application or the download link to the local provider's SAML metadata.
  • Assertion Consumer Service URL: specify the assertion consumer service URL. This is the service provider endpoint that will receive SAML responses.
  • X.509 Certificate: string with the base-64 encoded X.509 certificate.
  • Email Attribute: TODO: add definition.
  • Select How Users Will Execute Signatures: the method which users will use to execute signatures.

Incomplete Configuration:

 

incomplete_SSO_config.png

Complete Configuration:

 

complete_sso_config.png

Uploading a Metadata File

The user can also click the "Upload metadata file" button and provide a metadata file (XML file) with their SSO configuration. The application is going to take this file, parse all the information contained in it, and fill out all the fields automatically.

up_metadata_file.png

Advanced Parameters and LDAP Parameters

There are extra fields where the user can add new information if and when needed. They are called Advanced Parameters and LDAP Parameters. At first, they'll be hidden since they're not necessary depending on the configuration. The user should click "Show advanced settings".

 

show_advanced_settings.png

This button will open the list of additional settings that are available. When the user selects a provider in the Provider field other than the Other option, the application will set some default values on the advanced and LDAP parameters. If the Other option is selected, they will need to add a name for it.

 

Advanced Settings:

adv_settings_1.png

adv_settings_2.png

A Single Sign-On configuration may have one or many domains associated with it. The registered domains are the ones that will be used to login. Every domain item has:

  • Activation state:
    • Green checkbox: verified
    • Hourglass: not verified
  • Domain Name
  • Test login icon, which is shown in case the domain is verified
  • Action buttons:
    • Verify domain: triggers the domain verification flow
    • Disable: disable the domain, invalidating its verification

av_settings_3.png

  •  

Electronic Signature Options

For electronic signatures within the application (e.g., approving documents, completing training), you have the following options:

  • PIN number -- this is the default method. The first time users attempt to sign something, they are emailed a PIN number that is valid for the duration of the current session until they're logged out.
  • SAML re-authentication -- when signing, users are redirected back to the identity provider login screen and then back into ZenQMS once authenticated. This is simple to configure on our end and made possible via the SAML ForceAuthn attribute. While many do, not all SAML 2.0 compliant backends support this attribute.
  • LDAP -- a bit more difficult to configure and not commonly available, but a more familiar workflow for users. In order for this method to be supported, our servers must be able to reach the LDAP servers over the internet. See below for further details.

Additional information required for LDAP e-signatures

Basic Information:

  • Hostname or IP Address
  • Port Number
  • Authentication Type (e.g. Basic)
  • Distinguished Name Pattern for Binding - If the username entered is insufficient detail for binding to the LDAP server, the DN pattern to use with the username entered (e.g. "uid=<username>,ou=Users,dc=phakepharma,dc=com")

For LDAP Queries (to verify that the email address of the credentials supplied match the email address in our system):

  • Search Base DN (e.g. "DC=phakepharma,DC=com", the path from which all user accounts can be queried).
  • DN and password of an account authorized to query the user's email address (needed only if users cannot query their own account).
  • Query filter for returning only the relevant data containing the user's email address (e.g. "(objectClass=inetOrgPerson)" or "(cn=*)").
    List of username attributes that might be entered by users for authenticating/binding. For Active Directory this is usually "userPrincipalName" and "sAMAccountName". For other LDAP servers, this is often "uid".
  • Name of the email address attribute returned by the query (e.g. "mail").

If you need to open firewall access to our servers to accommodate LDAP requests, these are the IP addresses we currently use for our environments:

  • Production: 23.23.232.189, 23.21.164.2, 34.205.70.108, 52.24.250.107, 54.245.82.184, 54.71.223.87
  • Sandbox and Test: 34.226.223.211

Adding a Domain

Note: at least one domain should be verified before enabling SSO. 

To add a domain, the user should click on the "Add Domain" button. A modal will pop up.

add_domain.png

After the user enters the domain and clicks the Save button, they'll be redirected to the next step, which shows a hash string that will need to be added to their domain's provider configuration in order to be verified later.

add_domain_2.png

Verifying a Domain

After the creation, the user should verify the domain they just added. For this, they should copy the hash string provided in the last modal step and add on their domain's provider configuration in the TXT Records. After that, they should come back to the application and click the Verify Domain button. The application will show a modal with the same hash string that was provided when the domain was created, which is helpful in case the user somehow lost it. There are two options for the user: they can Cancel the verification request or Proceed with verification by clicking one of the buttons. If it's canceled, the modal closes. If the user proceeds with the verification, our backend will try to validate the TXT Record provided for the given domain and on a successful verification it'll be activated, otherwise it'll stay unverified.

verify_domain_1.png

verify_domain_2.png

Disable a Domain

In order to disable a domain, the user should click on the Disable button in the domain list.

disable_button.png

 

Enabling a Single Sign-On Configuration

Note: at least one domain should be verified before enabling SSO. 

A Single Sign-On configuration can be activated by switching the toggle in the table. Under the "Enabled" column, select the slider to enable.

enable_sso.png

If the user wants to test it, they should open the configuration by selecting the Provider name on the left to open the configuration. Next, scroll down to the domain below "Add and Verify Domains". From there, the user should click on the Test login icon and try it out.

test_login.png

***If you are prevented from logging on via SSO after enabling configuration but before verifying the domain, you should return to the app login page(app.zenqms.com), authenticate with email/password (reset if necessary) to continue. Note that the "password" is not the same password as your SSO provider, it's the password in our ZenQMS application for non-sso accounts.

 

Renewing your Certificate

  • Navigate to your target environment (app.zenqms.com or sandbox.zenqms.com).
  • Navigate to the Settings module.
  • Navigate to Settings > Account > Single Sign-On (SSO).
  • Select your target SSO configuration. 
  • Update your certificate under "X.509 Certificate".

SSO Related Articles

Login Journey

Completing an E-signature and Reviewing Assigned Workflows

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.