Configuring SAML Single Sign-on

This topic is for Secret Server v10.5 and later and assumes you have a running Identity Service Provider (IDP) with a signed certificate.
Secret Server does not support using SAML when Integrated Windows Authentication (IWA) is enabled.
This topic applies to Secret Server 10.5 and later.

SAML Overview

Secret Server allows the use of SAML Identity Provider (IDP) authentication instead of the normal authentication process for single sign-on (SSO). To do this, Secret Server acts as a SAML Service Provider (SP) that can communicate with any configured SAML IDP.

In the diagram below, Secret Server acts as the service provider. Any configured SAML IDP can be used for this process and there are several well tested providers, including OKTA, OneLogin, Azure ADFS, and Microsoft ADFS.

Figure:Secret Server as a SAML Identity Provider

image-20200610164654958

Prerequisites

Licensing and Version

Secret Server Professional Edition or higher, upgraded to version 10.5 or later. To install a new SAML license, go to Admin > Licenses > Install New License.

.NET Framework 4.6.2+

To use SAML 2.0, you must install .NET Framework 4.6.2 or higher on your Web server. This allows Secret Server to use Microsoft's "next generation" CryptoNG API for signing SAML requests, instead of being limited to the much older CryptoAPI. This is often necessary to use modern SSL certificates and is strongly recommended as a security best practice.

To download and install the latest version of .NET Framework: See Microsoft .NET Framework 4.8 offline Installer for Windows for the latest version as of when this topic was written. If you have already installed Secret Server on the same Web server, you have already done this.

Administer Configuration SAML Role Permission

The "Administer Configuration SAML" role permission is required to use SAML to access Secret Server. To grant a user this permission from an administrator account:

  1. Go to Admin > Roles. The Roles page appears.

  2. Click the Create New button. The Role Edit page appears:

    image-20200610145830073

  3. Type the name, such as SAML, in the Role Name text box.

  4. Click to select the Enabled check box.

  5. Click Administer Configuration SAML in the right side Permissions Unassigned list box.

  6. Click the < button to move the permission to the other side.

  7. Click the Save button. The Roles page returns.

  8. Click the Assign Roles link of the newly created role. The View Role Assignment page appears:

    image-20200610150702026

  9. Click the Role dropdown list to select the role you just created.

    image-20200610150844712

  10. Click the Edit button. The Role Assignment page appears:

    image-20200610151025938

  11. Move the desired users to the Assigned list using the same method as before.

  12. Click the Save Changes button.

Setting up Secret Server

  1. Navigate to Admin > Configuration.

  2. Click the SAML tab:

    image-20200610151801952

  3. Click the Edit button in the SAML General Settings section.

  4. Click to select the SAML Enabled check box.

  5. Click the Save button.

  6. Once you have SAML setup on our identity provider, then under General Settings, click Edit, then check the SAML Enabled checkbox. Save changes.

  7. Click the Edit button in the SAML Service Providers section.

  8. Type a name for your Secret Server service provider, such as SecretServerServiceProvider, in the Name text box.

  9. Click the Select Certificate link. The Upload Certificate popup appears:

    image-20200610152423326

  10. Click the Upload Certificate button to upload the certificate used for Secret Server's HTTPS configuration.

    What type of certificate can be used?

    • The uploaded SAML certificate requires a .pfx file format.

    • For on-premises instances: The uploaded certificate should match the one used for Secret Server's HTTPS configuration, or it can be created as a self-signed certificate using this PowerShell script.

    • For Secret Server Cloud users: Generate your own certificate using the same PowerShell script.

      Run the referenced PowerShell script as an administrator on a machine with .NET 4.5 or above and replace the variables in the script as directed. Your certificate is created in the directory from which you run the script. The subject name on the certificate is irrelevant, though for on-premises instances it typically matches the URL of the instance.

  11. Locate your certificate .pfx file and select it.

  12. Click the Open button. The new certificate appears.

  13. Type the access password for the private key of the certificate in the Password text box.

  14. Click the OK button. The certificate is uploaded and tested, and the popup disappears. The certificate now appears in the SAML Service Provider Settings section.

    If you have an outdated version .NET Framework (earlier than 4.6.2), you may see an error recommending you upgrade to fix the error. Reload the certificate after you do so.

  15. Click the Save button.

  16. Click on Download Service Provider Metadata (XML) to download the SecretServerSAMLMetatdata.xml file. This file is needed when setting up SAML on your Identity Provider.

  17. Set up your Identity Provider using the SecretServerSAMLMetadata.xml file from the previous step.

  18. Click the Create New Identity Provider link. An Identity Provider popup appears.

  19. Click the Import IDP from XML Metadata button.

  20. Navigate to your SecretServerSAMLMetadata.xml file and select it. This is used for uploading into your IDP, which varies by provider. Follow instructions in the following section..

  21. Click the Open button.

Setting up IDPs

IDP setup varies by provider. Go to the TDP Integration site for instructions for your provider.

The username returned from the IDP to Secret Server within the SAML Response/Assertion's subject statement must match the desired format. The format of the username passed depends upon how the user was created within Secret Server.
If AD Sync was used to create Secret Server users, the username returned from the IDP must match this format: SecretServerUsername@ADsyncDomain orADsyncDomain\SecretServerUsername. If using SLO, ensure that the NameID is set correctly in the IDP as an outgoing claim for the Secret Server Service Provider. If a user has different sAMAccountName and userPrincipalName in Active Directory, custom rules in the IDP can be created.

Lockout Workaround

Locked Out? Here's how you get around SSO. If during the configuration process for SAML you lock yourself (as an administrator or a user) out of Secret Server, you can log on Secret Server without using the SSO workflow by using this URL string:

[YourSecretServerInstanceName]/login.aspx?preventautologin=true

The role permission needed for this is "Bypass SAML Login," which admins have by default.