Single Sign on Basics

Updated 2 months ago by Leigh Hutchens

Before setting up SSO in Quinyx, it’s important to go through the basics to simplify the setup. SSO is short for Single Sign-On, and in Quinyx it's used to move authentication from the built-in ways of authenticating users via, for example, a username and password to a customer-controlled way.

SSO can provide numerous improvements such as security, compliance, and simplicity over username and password - but most importantly, it gives the customer control over login and authentication to Quinyx.

Quinyx SSO chapters

Configuring and using SSO can be split into different chapters:

  1. Technical trust between two systems
  2. Data mapping
  3. Login to Quinyx using SSO for employees

Technologies and protocols

As SSO has developed over the years, a number of protocols and standards have been established to simplify SSO between different systems. Two common protocols supported by Quinyx are SAML 2.0 for Web and OpenID Connect (OAuth2) for mobile apps.

Over time more protocols might be supported by Quinyx.

The protocols exist to simplify implementation and compatibility between different systems so each vendor, Quinyx in this case, doesn't have to build specific support for each type of provider (Azure ADFS, Onelogin, Okta, Google, etc.) - we all speak a common language. What's common among all protocols is that they have a list of settings such as certificates, URLs, and potential secrets that need to be shared to establish the trust between the two.

While the URLs can look different between different vendors, they all provide the same functionality as they are compatible with the protocol specified.

Over time more protocols might be supported by Quinyx.

Technical trust between two systems

A prerequisite for SSO to work between Quinyx and the customer's IT environment is to establish the technical trust between the two parties. This is done once and often by the IT-department responsible for the system at the customer. Quinyx UI provides a self-service way of entering all settings required to establish the trust between Quinyx and the customer-chosen system.

This is where all the URLs, secrets, and certificates are used to once configure and establish that trust. To simplify this process in SAML 2.0, all the required information can be stored in a “metadata” file to be shared between the parties. This file minimizes the risk of typos and misconfiguration, as it contains all the information needed that can be used to configure the trust. OpenID Connect has similar instructions called “Well Known URIs” which is a weblink containing all the URIs needed to set up OpenID (often ends with /.well-known/openid-configuration).

You can find technical guides about establishing trust here and here.

Data mapping

When the Technical trust has been established, the two systems can communicate during login; however, there is still one thing left to configure and that is the Data mapping. The customer system, from here called IDP (IDentity Provider), provides a database of the employees who are subject to login into Quinyx. The IDP can be built up of many different systems internally at the customer with high complexity, or it can be a single system in its most simple form, almost like a spreadsheet containing all the employee information.

When an employee uses SSO to login towards Quinyx, different properties of the user from this “Database” are sent to Quinyx as a part of the protocol used.

The above is an example of data sent from the customer to Quinyx during login, also called Claims.

While the protocols used for establishing the trust have certain specific details and recommendations, it doesn't decide exactly what all fields should contain, this requires configuration of the Data mapping. Many providers of OpenID Connect have some common claims which, for example, contain an email address in a certain Claim (field). One specific Claim might not fit every Quinyx customer so we allow the customer to choose which one to use.

Configuring the Data mapping

The goal of Data mapping is to connect the information about an employee in the customer IDP/Database to the information about the employee in Quinyx so Quinyx can identify who is logging in.

This requires us to choose a field/property from Quinyx and one on the customer IDP/Database to match each other to uniquely identify that user. The fields chosen are entered into the configuration page in Quinyx for SSO. More information can be found here.

Example data

Example data in Quinyx (left) and on the Customer side (right).

Username and email configured

First attempt to do the data mapping; The property email is chosen to be used in Quinyx and the username is chosen from the customer data.

The login fails since the information doesn't exactly match on both sides.

Email and UPN configured

Reconfiguring to use email and UPN gives a different outcome.

The login is now successful as Quinyx can uniquely identify the user as the correct John Doe from the customer.

How to decide which one to use

Since the protocol doesn't specify exactly which data to use during SSO the recommendation is to identify data available in both systems before setting up SSO and find a suitable field to map users. As customer IDPs are often highly configurable, it's possible to modify what data is sent in which fields to Quinyx to help out in the data mapping process - the important part is that it's decided which field to use and ensure the data is consistent.

If no data can be found to map each user, new information in either of the systems needs to be created. This can be any type of unique number or string unique for each employee. Using integrations towards Quinyx and updating each employee with automation would simplify this process to avoid manual configuration of required data for login.


How Did We Do?