SAML 2.0

Turbo Server supports logging in users via Single Sign-On (SSO) using an external identity provider that supports SAML 2.0 authentication. The SAML 2.0 authentication protocol is supported by many identity providers, such as AzureAD, ADFS, and WSO2.

Prerequisites

The following section describes the requirements to use SAML 2.0 with Turbo Server.

Identity Provider Account

You must have access to an identity provider (IdP) that supports the SAML 2.0 protocol and an account that has permission to create and configure an application with that IdP.

Turbo Server Configuration

Single Sign-On requires all servers in the farm to use https in order to keep users data secure. Make sure SSL is enabled during installation or install SSL from the Domain > Servers > Server page.

Turbo Server must be configured to use SAML 2.0 authentication with configurations obtained from the IdP from the Users > Authentication Method page.

Identity Provider Attibutes and Claims

SAML 2.0 obtains a response token from the identity provider containing user information during the authentication process. Turbo Server uses the following token attributes and claims to create or login to the associated Turbo account:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier or nameID - Used as the Turbo account username.
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname - Used in combination with surname as the Turbo account display name.
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname - Used in combination with givenname as the Turbo account display name.
  • http://schemas.xmlsoap.org/claims/group - User groups to which the Turbo account will be assigned.

The identity provider must be configured to accept the requested attributes and claims.

Certificate File

Turbo Server uses the SAML Signing Certificate to verify that the SAML response received during login is signed by the expected identity provider.

This certificate file is provided by your identity provider and must be manually installed on the Hub server. Please refer to the provider-specific documentation for more information on locating and installing this certificate.

How Turbo Users and Groups are created

When SSO is configured, a Turbo Server user will be created on a successful login if the user does not already exist. Users are created using the name identifier, given name, and sur name attributes and claims as specified in the Identity Provider Attributes and Claims section. User groups received in the groups claim will be created and the user assigned to them on each login. Users must be manually removed from the Turbo Server if removed in the external identity provider.

Automatically created user groups from SSO will be created in the Single Sign-On directory service. The user's group membership will be automatically removed from the group if removed in the external identity provider on the next sucessful login. If the SSO user is manually added to an internal group, then the user's group membership must also be manually removed.

Supported Identity Providers

Turbo Server supports Single Sign-On against any identity provider that supports SAML 2.0 authentication. Setup guides are available for the following identity providers:

For other identity providers, please refer to the identity provider documentation for information on configuring the claims listed in the Identity Provider Attributes and Claims section, as well as how to obtain the fields required by the Turbo Server user authentication form.

Troubleshooting

If an error is reported by the Turbo Server after logging into the external identity provider, the first place to check will be the Hub logs.

Failed to validate SAML token

Error log located in the API log file:

04/07/2020 17:44:42.6736 - Critical - 0x070C: Failed to validate SAML token: System.IdentityModel.Tokens.SecurityTokenValidationException: 
The X.509 certificate CN=Microsoft Azure Federated SSO Certificate is not in the trusted people store. 
The X.509 certificate CN=Microsoft Azure Federated SSO Certificate chain building failed. 
The certificate that was used has a trust chain that cannot be verified.
Replace the certificate or change the certificateValidationMode. 
A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.

The Hub server failed to validate the SAML token. This can be caused by a missing or invalid SAML Signing Certificate. Please ensure that the SAML Signing Certificate has been added to the certificate store.

04/07/2020 17:44:42.6736 - Critical - 0x070C: Failed to validate SAML token: System.IdentityModel.Tokens.SecurityTokenException: The issuer of the security token was not recognized by the IssuerNameRegistry. To accept security tokens from this issuer, configure the IssuerNameRegistry to return a valid name for this issuer."

The Hub server did not recognize the token issuer identified by the Signing Certificate Thumbprint and Signing Certificate Common Name. This can be caused by missing or invalid Signing Certificate values. Please ensure that the correct values were configured in Turbo Server, and that the Signing Certificate has been added to the certificate store.

Questions? Talk to us.