Configuring SAML Single Sign-on

This topic is for Verify Privilege Vault v10.5 and later and assumes you have a running Identity Service Provider (IDP) with a signed certificate.
Verify Privilege Vault does not support using SAML when Integrated Windows Authentication (IWA) is enabled.
This topic applies to Verify Privilege Vault 10.5 and later.
Sometimes SAML validates despite having an expired IDP Certificate. This is because the SAML certificate exchange is actually a key exchange—the SAML protocol uses the public/private keys contained within the certificate to secure the communication. Unlike a website's certificate, it is not the URL or metadata within the certificate that is used to help secure the connection, only the key exchange. If the certificate provided by the IDP has been renewed but still works without a change in Verify Privilege Vault, it means the key is identical, and only the metadata, such as the expiration date, has changed. This is why it does not fail validation—the key is for validation and it has not changed. Had the key changed, Verify Privilege Vault would not be able to decrypt the SAML messages, and would therefore fail. IBM Security does not view this as a security problem and offers this note for clarification.

SAML Overview

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

In the diagram below, Verify Privilege Vault 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:Verify Privilege Vault as a SAML Identity Provider

image-20200610164654958

Prerequisites

Licensing and Version

Verify Privilege Vault 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 Verify Privilege Vault 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 Verify Privilege Vault on the same Web server, you have already done this.

Administer Configuration SAML Role Permission

The "Administer Configuration SAML" role permission is required to configure SAML settings (no specific permission is required to access Verify Privilege Vault via SAML). To grant a user this permission from an administrator account:

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

  2. Click the Create Role button. The Create Role window appears:

    image-20200610145830073

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

  4. Click to select the Enabled check box.

  5. Click Create Role. The role is created and the role page is now opened.

  6. Under the Permissions tab, click the Edit button.

  7. Select All next to the search box, select Administer Configuration SAML from the list, and click Save.

  8. Under the Assignments tab, click Edit, select All next to the search box, select the users that you would like to assign to the role, and click Save.

Setting up Verify Privilege Vault

  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 Verify Privilege Vault 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 Verify Privilege Vault'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 Verify Privilege Vault's HTTPS configuration, or it can be created as a self-signed certificate using Generating Self-Signed Certificates for Scripts.

    • For Verify Privilege Vault 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.

  21. Click the Open button.

Setting up IDPs

IDP setup varies by provider. For Entra ID, go to Setting up Entra ID for SAML. For all other IDPs, go to the TDP Integration site for instructions for your provider.

The username returned from the IDP to Verify Privilege Vault 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 Verify Privilege Vault. Users must be present in the User Management section to set up SAML.
If AD Sync was used to create Verify Privilege Vault 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 Verify Privilege Vault 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 Verify Privilege Vault, you can log on Verify Privilege Vault 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.

Generate a Self-Signed Certificate for Secret Server Using PowerShell

Overview

Included in this article is the script and steps required to generate a self-signed certificate, which can be used for the SAML configuration in a Secret Server instance. For additional information, please refer to Configuring SAML Single Sign-On above.

Step-by-Step Instructions

1. Replace the variables in the script, as directed.

2. Run the PowerShell script as an administrator on a machine with .NET 4.5 or above.

Copy 
# This simply generates a self-signed certificate which can be imported into Secret Server
# Replace the variables below (pass, dnsname, filename)
# Requires .NET 4.5 or above
# Please Run As Administrator
###--Variables to Replace--###
# Certificate Password for PFX
$pass = 'PASSWORDHERE'
# DNS name in certificate
$dnsname = 'DNSNAMEHERE'
# Filename of PFX
$filename = 'PFXNAMEHERE.PFX'
###--Commands--###
# NOTE: The provider must be set in order to be compatible with .NET 4.5 newer versions of .NET can import certs from more providers
$securepass = ConvertTo-SecureString -String $pass -Force -AsPlainText
$cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname $dnsname -HashAlgorithm SHA256 -KeyLength 4096 -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider"
$path = 'cert:\localmachine\my\' + $cert.thumbprint
Export-PfxCertificate -cert $path -FilePath $filename -Password $securepass
# remove from cert store
Remove-Item $path

The self-signed certificate will be created in the directory from which the script was run (e.g., C:\Users\Administrator).

Note that the subject name on the certificate is irrelevant. Although for Secret Server On-Premises, it typically matches the URL of the instance.