When Single Sign-on (SSO) is enabled for a user, Vault does not validate that user’s password. Instead, Vault relies on an external identity provider to authenticate users and pass information (“assertions”) about the users in web browser requests. This article provides technical details of SSO in Vault. For basic information, see Single Sign-on Basics. For details on setting up SSO, see Configuring Single Sign-on.
As a cloud application, Vault requires that a customer’s IdP is accessible from the internet, either directly or through some kind of broker or gateway.
Vault can integrate with a customer’s internal Microsoft Active Directory (AD) implementation through a third-party identity management solution. Many of our customers have successfully integrated Vault with Okta, Ping Identity, and ADFS.
Supported SSO Types
Vault supports SSO using Security Assertion Markup Language (SAML) 2.0 for both Service Provider (SP) initiated and Identity Provider (IdP) initiated models. For Vault, both SSO models can be used with either HTTP POST or HTTP Redirect binding.
IdP-Initiated SAML Login Process
The following diagram and steps detail how SAML login, using and IdP-initiated login flow, works for Vault.
- Admin establishes a trust relationship between the IdP and the SP by providing a certificate to the SP that the IdP has generated. Any communication from the IdP to the SP has to be ‘signed’ with this certificate.
- A user logs into the IdP with her credentials.
- The user selects an application (SP) from a list managed by the IdP.
- The IdP returns a SAML response that is digitally signed by the IdP with its certificate.
- The browser takes the SAML response and posts it to the SP. The SP confirms that the response is properly signed and, if so, gives the user access to the application.
SP-Initiated SAML Login Process
The following diagram and steps detail how SAML login, using and SP-initiated login flow, works for Vault.
- Admin establishes a trust relationship between the IdP and the SP by providing a certificate to the SP that the IdP has generated. Any communication from the IdP to the SP has to be ‘signed’ with this certificate.
- The user opens the application (SP) website.
- If the user’s authentication doesn’t exist because she has never logged in or the session has expired, the SP contacts the IdP by sending a SAML AuthnRequest. The following steps apply only if the user is not already authenticated.
- The IdP displays a login window for the user.
- The user logs into the IdP with her credentials.
- The IdP returns a SAML response that is digitally signed by the IdP with its certificate. The browser takes the SAML response and posts it to the SP.
- The SP confirms that the response is properly signed and, if so, gives the user access to the application.
SSO Automatic Redirect to IDP
Customers who exclusively use SAML SSO with Vault, i.e., those with no password-based security policies, will be automatically redirected to the Vault login page to their SAML IDP login page and then automatically signed into Vault after their IDP has verified their credentials.
Note: If all users in a Vault are SSO users configured with the same security policy, Vault automatically redirects the browser to the IdP login page. Due to the cache involved, it could take up to 60 minutes for Vault to change the behavior.
SSO IDP Login Button
Customers with multiple Vault security policies have a choice between logging in directly with their Vault username and password or logging in through their Identity Provider (IDP). This feature makes it easier for customers using SAML for Single Sign-on to log into Vault by allowing Admins to add a custom login button to their login page. This allows Vault users to easily identify their login options – log into Vault with a username and password or click the custom login button to log in through their IDP. The login button can also be customized to include the company logo, colors, and messaging.
About Deep-Linking
Deep-linking defines the ability of a user to navigate to a specific page within Vault while authenticating through SAML.
Vault supports deep-linking through both IdP-initiated and SP-initiated SAML flows. If a user has never visited the Vault or never logged in successfully through their IdP, the SP-initiated flow is used. Once a user logs in successfully through their IdP, Vault sets an IdP cookie and all subsequent deep-linking flows are accomplished through an IdP-initiated flow. The IdP-initiated flow is also used when a custom Identity Provider button is used.
The information for deep-linking is usually carried on a query parameter called RelayState. However, the requirements around how the parameter’s name and encoding vary from IdP to IdP. For example, Ping Identity requires the parameter to be called TargetResource instead of RelayState. Microsoft Active Directory Federation Services (ADFS) also has unique requirements for configuring the RelayState.