SAML 2.0 Single Sign-On

Turbo Server can be configured to use Single Sign-On (SSO) to login users using an external identity provider that supports SAML 2.0 authentication, such as Azure AD, ADFS, or WSO2.

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.

When SSO is configured, a Turbo Server user will be created on a successfull login if the user does not already exist. User groups received in the group claim will also 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.

Configure Azure AD

The following section describes how to integrate Turbo Server with Azure AD SSO using SAML 2.0.

To enable Azure AD SSO, a new Enterprise Application must be registered in your Azure AD tenant. From your Azure AD homepage, click Enterprise applications and then New Application. Enter your desired name then click Add.

AzureAD SSO + SAML 2.0 add enterprise application

Once the application has been created, click on the Single sign-on tab and select the SAML authentication method.

AzureAD SSO + SAML 2.0 select authentication method

Once selected, you will need to configure the application to point to the correct Turbo Server URLs. Please configure the following settings and claims:

Basic SAML Configuration

  • Identifier (Entity ID): - A unique identitier that will be the audience of the SAML response. For example: https://example.turbo.net.
  • Reply URL (Assertion Consumer Service URL): The default reply URL for the SAML response. This must match the endpoint listed on the Turbo Server authentication method page. For example: https://example.turbo.net/auth/saml/return.

User Attributes and Claims

  • Unique User Identifier (Name ID): The claim that will uniquely identify the user and will be used for their Turbo Server username. This claim must have the following properties:

    • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
    • Name: nameidentifier
    • Format: Email address
    • Source Attribute: user.userprinciplename
  • Given Name: The claim that will be used for the user's first name display in Turbo Server. This claim must have the following properties:

    • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
    • Name: givenname
    • Source Attribute: user.givenname
  • Surname: The claim that will be used for the user's last name display in Turbo Server. This claim must have the following properties:

    • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
    • Name: surname
    • Source Attribute: user.surname
  • Group: The group claim that will be used to assign group membership for the user in Turbo Server. This claim must have the following properties:

    • Namespace: http://schemas.xmlsoap.org/claims
    • Name: group
    • Source Attribute: DNSDomain\sAMAccountName
    • Emit groups as role claims: unchecked

AzureAD SSO + SAML 2.0 configration

Users and Groups

On the Users and groups tab, add the users and groups that will have permissions to login with this application.

Azure AD SSO + SAML 2.0 user and groups

Configure Turbo Server

Once you have configured Azure AD, you are ready to enable SSO on Turbo Server.

Open the Turbo Server administration site and navigate to the Users > Authentication Method page. Change the Authentication Method to Single Sign-On and the Single Sign-On Method to SAML 2.0.

Azure AD SSO + SAML 2.0 server settings 1

Fill in the following fields according to the Azure AD configuration:

  • Application Id: The Application Id as configured in the Azure AD Overview section.
  • Issuer: The Identifier (Entity ID) as configured in Azure AD Basic SAML Configuration section.
  • Entry Point: The Login URL as configured in Azure AD Set up [Application Name] section.
  • Logout URL: The Logout URL as configured in Azure AD Set up [Application Name] section.
  • Signing Certificate Thumbprint: The Thumbprint as configured in Azure AD SAML Signing Certificate section.
  • Signing Certificate Common Name: The Common Name as configured in Azure AD SAML Signing Certificate section.

Azure AD SSO + SAML 2.0 server settings 2

Install the SAML Signing Certificate

The SAML Signing Certificate is used by Turbo Server to ensure that the SAML response is signed by the expected identity provider. This certificate must be manually installed on the Hub server.

First, download the certificate from Azure AD. This can be found listed as Certificate (Base64) in the SAML Signing Certificate section:

AzureAD SSO + SAML 2.0 certificates

Next, login to the Windows Server machine that the Hub server is installed on as an administrator. Install the certificate with the following steps:

  1. Select Run from the Start menu and enter mmc.
  2. Click on File then click Add/Remove Snap In.
  3. Select the Certificates option then click Add
  4. Select Computer account, select Local computer, and then complete the dialog.
  5. Click on the new Certificates Snap In, then click All Tasks > Import... SAML Certnstall
  6. Select Local Machine and click Next SAML Cert Install 2
  7. Select your certificate and click Next SAML-cert-install-3
  8. Select Place all certificates in the following store, select Trusted Root Certificate Authorities, and then click Next SAML-cert-install-4
  9. Complete the rest of the import wizard with the default options.

Once installed, Turbo Server portal logins should now complete successfully.

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, see Install the SAML Signing Certificate.

Questions? Talk to us.