ZenQMS SSO Single Sign-On Self Service

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

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.

It is highly recommended to read the entirety of this article before proceeding. Always configure and test in your Sandbox environment before implementing in Production.

Helpful Links:

ZenQMS SSO Configuration Details (Use these details to complete your SAML configuration)

SSO Compatibility with ZenQMS

SSO (Single Sign-On) Set-Up for Administrators & FAQs

Enabling a User to Configure SSO
Configuring or Editing your Single Sign-On Solution
Uploading a Metadata File
Advanced Parameters and LDAP Parameters
Electronic Signature Options
Additional information required for LDAP e-signatures
Adding a Domain
Verifying a Domain
Disable a Domain
Enabling a Single Sign-On Configuration
Renewing your Certificate

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.

To add this permission to a role or creating a role with this permission

Navigate to your target environment (app.zenqms.com or sandbox.zenqms.com) and click Settings.

Navigate to Account - Roles/Permissions.

Create a role with the Account Single Sign-On (SSO) permission box checked/enabled by selecting Create a Role, or add this permission to an existing role:

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

Click on the Settings icon.

Navigate to Account - Single Sign-On (SSO).

Once there, you 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

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 to configure a new SSO connection or select and existing Provider name to open an existing configuration. The slider with an empty form or the current configuration details will open. You may manually enter in your SSO data or upload a metadata xml file to auto fill the data. See "Uploading a Metadata File" below.

The fields available at 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.

The data in this view may be entered manually by the end user or a metadata xml file may be used to upload the data.

Incomplete Configuration View

Complete Configuration View

Uploading a Metadata File

The user may select 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. See the button circled below:

Once you upload the metadata file, the data will autofill the fields in the form. You will only need to add the appropriate SSO "Provider".

Advanced Parameters and LDAP Parameters

Note: If none of these advanced parameters are needed, please skip to the next section, "Adding a Domain".

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:

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

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

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:

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. This is the DNS record, a TXT type, for you to add to your SSO configuration. Copy and save this record name for adding to your SSO configuration. Do this step before verifying your domain:

Verifying a Domain

Note: Verify your domains and then enable your SSO. You cannot verify the domain and not enable the SSO, you will not be able to login. The verify domain and enabling the SSO are steps one and two of enabling your SSO in ZenQMS.

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 adding and saving on their side, 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. A green check will appear next to a verified domain:

Disable a Domain

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

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:

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.

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