Single Sign-On, or in short SSO, is an authentication approach that allows users to access numerous applications using a single set of login credentials. You need an SSO Identity Provider (IdP) to configure your platform as an external application to create a SSO login on the platform. In the instruction below we explain how you can enable it on the platform with the SAML 2.0 or Open ID protocol.

SAML 2.0

You can find the TinQwise service provider metadata at the following link: [domain.platform.co.nl]/saml2/metadata/. Communicate this link to your IT department to configure the SAML2.0 connection on their end.

To add a SAML2 integration here click the 'Add SAML2' button under "Users - Integrations".

The "Name" will be shown in the login screen, so something like "Single Sign On" is a good pick.

In the "Metadata url" field, put the "Identity Provider" metadata url you received from your IT department. An example of this value is https://login.microsoftonline.com/something-something/federationmetadata/2007-06/federationmetadata.xml?appid=0123456789ab-abcd-abcd-abcdef012345

To allow usage of the SSO and show the SSO login button on the login screen, make sure "Activate identity provider" is checked.

If you want to create users when they log in through SAML, check "Create unknown user". If you want to update their email addresses, names, and groups every time they visit, check "Update existing user".

Identifying users

To correctly identify which user is attempting to log in through SAML, we need to know what fields to compare. Typically, the field nameid from the identity provider is compared with the saml_username field in TinQwise:

Another often-used option is to match the email claim from the identity provider with the email field in TinQwise:

If the user cannot be found with the given identifier (email or something else) login will fail with a "user can not be found" message.

Creating and updating users (optional)

When the "Create unknown user" and/or "Update exising user" options are selected, you must fill in which claims should be used to fill user information in TinQwise. Please see the SAML Configuration article for more information.

Testing the connection

After saving the form, an extra login button will appear on our login screen of your platform.

You can test the connection from an incognito window by clicking the SSO button and signing into the SSO login screen, afterwards you get redirected to the platform with a successful sign-in if the connection is setup correctly.

In case of a failed login attempt, the TinQwise team needs to know the platform and username of the test user so we can troubleshoot the login information in our back office systems.

There are more advanced settings for the SAML SSO and please look at this article for the advanced set-up like:

Create new users and update existing users
Assigning users to groups

Extra info for Entra ID (Azure AD) with SAML2.0

For connecting the platform to your Entra ID (formerly known as Azure AD) over SAML2.0 please follow the steps provided by GE here: Configure Azure Active Directory as the Identity Provider (IDP)

Extra info for Active Directory or ADFS connections

ADFS is a layer on top Active Directory to communicate with the outside world. The protocol we use for that is still SAML2.

You receive from us the location with the metadata information: [domain].platform.co.nl/saml2/metadata/
- You create a new application in ADFS, using our metadata
- You add certain claims to the application, which basically means: which fields from their AD are added to the connection
- We require at least: first_name, last_name, email. The claim attribute information
- In addition they can provide extra fields that would be stored in the profile and can be used four assigning groups in advanced settings.
You provide us with the metadata url from their newly created ADFS application. You can add this metadata url to the Control in the same steps as described above.

Refreshing SAML metadata

The SAML metadata contains a certificate which is used to verify the authenticity of logins. This certificate is typically valid for a year. The certificate must be updated before it expires.

The certificate is part of the SAML metadata. If your SAML provider on the TinQwise platform is configured with a metadata url, it is updated every morning at 06:00 UTC.

The metadata is also refreshed whenever you 'save' the SAML provider in control.

To make sure the process of updating certificates goes without interruption, we advise to add an additional certificate to the metadata a month before the old certificate expires. Start using the new certificate a few days before the old one expires. Remove the old certificate after it is expired.

Performing certificate rollover without service interruption:

One month before the old certificate expires: add an additional certificate to the SAML configuration in your identity provider (e.g., microsoft azure)
One week before the old certificate expires: start using the new certificate to sign SAML messages in your identity provider (e.g., microsoft azure)
When the old certificate expires: remove the certificate from the SAML configuration in your identity provider (e.g., microsoft azure)

When the rollover is performed in this manner, there is no manual activity necessary on the TinQwise platform.

Open ID Connect (OIDC)

To configure Open ID Connect SSO, please create a service ticket and provide us with the following information.

We support the "id_token" and "code" response types.

SSO url: this is the link shown on the login page to redirect users to the SSO login page of their identity provider.
Example: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id={client_id}&response_type=id_token&redirect_uri=https%3A%2F%2F{domain}.platform.co.nl&response_mode=fragment&scope=openid&state=&nonce=hello
Openid url: usually the public openid configuration url.
Example: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration
Identifier: This is the field from the openid message to match on the TinQwise user. On the TinQwise side, we first try to find a user with the same "openid_username" which can be manually set on someone's profile or automatically with a user import integration. If that's not possible we can match on email or username {identifier}@{platformname}.platform.co.nl.
Audience: optional field, used if you only allow users to login if they have the correct 'audience' specified in the openid message.

When using the "code" flow, we also need the following information:

token url: The url where we can exchange the code for a id_token, as well as credentials to access this endpoint.

Here is a Microsoft help article for setting up an Open ID Connect SSO in Entra ID (formerly known as Azure AD). We would like to know these fields:

tenant
client_id
response_type (must be id_token, as we don't support anything else yet)
scope