Configuring Vault For Single Sign On

OverviewVault provides integration with Microsoft’s Active Directory Federation Services (AD FS) to enable your users to have a Single Sign On experience when they access your organisation’s Web-based Vault application.As well as giving users a single sign on capability, AD FS also gives you the security control and management of the access credentials of your users without having to share these with a third party.

In its simplest form, AD FS operates in the following manner

Your user attempts to log into Vault

Vault refers the request to your Single Sign On server

Your Single Sign On servers verify the user against your Active Directory credentials

The verified details are passed back to Vault for Vault authorisation

If the user exists in Vault, the user is presented with the Vault home page

ResponsibilitiesVault IQ are responsible for;

Providing the SAML interface in Vault

Configuring the Vault interface with details supplied by you

You are responsible for;

Provision and configuration of all AD FS components

Provision of appropriately skilled resources for the above

Maintaining a valid token signing certificate and notifying Vault of any changes to the certificate used prior to rollover

Vault IQ will assist with integration of your AD FS services with Vault, however the skills and resources to configure ADFS / SAML are your responsibility.

Configuring Vault As a TrustedLinking Vault with your Active directory using ADFS requires the setup of a two-way trust using SAML. ADFS has to be configured to trust Vault as a relying party and Vault needs to trust the ADFS as an identity provider.

PrerequisitesADFS 2.0 (3.o) installed. Setup of the ADFS infrastructure is outside the scope of the document.

Note: Windows 2008 R2 ADFS role installs ADFS version 1.0. You will need to download and install ADFS 2.0 (3.0) from Microsoft.

Initial Vault InformationVault IQ requires the following information before it can setup the relaying trust.

Check Import data about the relying party published online or on a local network, Use the provided Federation metadata. It will have the following formathttps://companyid-01.vaultgrc.com/sso/module.php/saml/sp/metadata.php/COMPANYIDThen click Next. The metadata XML file is a standard SAML metadata document that describes Vault as a relying party.

Check Open the Edit Claim Rules dialog for this relying part trust when the wizard closes and then click Close.

You’re done configuring Vault as a relying party.

Configuring Claim Rules for the Vault Relying PartyIn these steps we’re going to add the claim rules so that the elements Vault requires and ADFS doesn't provide by default (Name Id, principal) are added to the SAML authentication response. If you forgot to check the box to launch the claim rule dialog, right-click on the relying party (in this case Vault) and then click Edit Claim Rules.

Click on Add Rule...

Select Send LDAP Attributes as Claims (Default) and press Next

Add a Rule Name and Select Active Directory as the Attribute Store.

In the grid add the items below. Note: principal is not in the drop down list and must be added manually.

'User-Principal-Name', 'Employee Number' or 'SAM Account Name' can be used

If you get any other page then recheck the settings and contact Vault IQ support with the error message.

Token Signing Certificate RolloverADFS Default BehaviourADFS automatically creates a new Token Signing Certificate 20 days before the current token signing certificate expires. ADFS will automatically switch to use the new signing certificate as the primary signing certificate after 5 more days (15 days until the expiry of old signing certificate).

Error ConditionIf Vault is not notified of the new certificate is used as primary without notifying Vault all attempts to login will fail with message in the stack trace:

Unable to find a certificate matching the configured fingerprint.

New Token Signing Key Procedure

Once the new key is generated (automatically or manually) the new certificate thumbprint is required to be sent to Vault (support@vaultgrc.com) for addition to the allowed list of thumbprints. At this stage, both thumbprints will be valid. Once the rollover is complete and the old certificate is removed from ADFS contact support to remove the old thumbprint.

By following this method users should not experience any downtime logging into Vault.