ZenQMS SSO Single Sign-On Self Service Guide

Joe • Created • Last updated
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. 

 

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 account. They will need the role permission 'Account Single Sign-On (SSO)' to perform these steps. All users assigned to the 'Administration: Account Super User' role will have this permission automatically.

 

Configuring or Editing your Single Sign-On Solution 

Navigate to the target environment (app.zenqms.com or sandbox.zenqms.com). Click on 'Settings >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.

SSO_Table.png

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. 

 

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: Must exactly match the user’s email address to successfully link the IdP account.
  • Select How Users Will Execute Signatures: the method which users will use to execute signatures.

 

For reference, see the slider before the SSO is configured;

sso.jpg

 

and here is the slider when the SSO configuration are completed.

finished.jpg

 

Uploading a Metadata File

The user may select the 'upload metadata file' option 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. You will only need to add the appropriate SSO provider before you can upload the file.

meta.jpg

 

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

advan.jpg

 

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.

long.jpg

 

Your SSO configuration may have one or many domains associated with it. The registered domains are the ones that will be used to login. 

verify.jpg

Every domain item has:

  • An activation state:
    • Green checkbox: verified
    • Hourglass: not verified
  • A domain name
  • A test login icon (which is shown in case the domain is verified)
  • Action button options:
    • 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
  • 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").

 

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

 

Click the 'add domain' option in the SSO slider. Add your company domain; click 'save and continue' when finished. A pop up will appear to allow you to copy the record. Copy the hash string that needs to be added to your 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. Do this step before verifying your domain.

step 2.jpg

 

Verifying a Domain

Note: Verify your domain(s) first, then enable your SSO. These steps must be done in this order to successfully enable your SSO. If you do not follow those steps, you will not be able to log in. If this happens, please reach out to the help desk to disable your SSO.

 

Now that the domain is created, it needs to be verified. Click the 'verify now' option. A pop up will open showing the same hash string that was provided when the domain was created, which is helpful in case the string is lost. There are two options shown: cancelling the verification request or proceed with verification. If it's canceled, the pop up closes. If the proceed with the verification option is selected, 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. 

proceed.jpg

 

A green check will appear next to a verified domain:

ploik.jpg

 

Disabling a Domain

To disable a domain, click on the 'disable' button in the domain list.

dis.jpg

 

Enabling a Single Sign-On Configuration

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

 

The SSO can be activated by switching the enable toggle on in the table. 

enabled.jpg

 

If you would like to test the SSO, open the configuration by selecting the provider name to open the configuration. Next, scroll down to the domain; from there, click on the 'test login' icon and try it out.

test.jpg

 

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). Click 'Settings >Single Sign On (SSO)'. Click on your provider's hyperlinked name. Update your certificate under the 'X.509 Certificate' section.

 

 

 

 

Enlarged view