Configuring SAML Profiles


In order to configure SSO, you must first create a SAML profile. Then, you must provision users to use the profile. Vault allows you to create multiple SAML profiles and associate each with a different identity provider. This allows users to authenticate with any IdP configured on the security policy to which they are assigned.

How to Create a SAML Profile

To create a SAML profile:

  1. Go to Admin > Settings > SAML Profiles
  2. Click Create
  3. Enter a Label and Name for the profile.
  4. Complete the SAML Profile configuration. See details below.
  5. Click Save

Obtain Information from your Identity Provider (IdP)

You need the following information from your IdP:

Identity Provider Certificate File Contains the public key for your identity provider in X.509 certificate format. Note that if the IdP replaces or updates their certificate, you must update the SAML profile with a new certificate. See Importing IdP Metadata below.
Identity Provider Login URL Redirect login URL for Vault that is typically generated by the identity provider when registering Vault as a service provider. This URL is customizable to support advanced deep-linking.
Identity Provider Logout URL OPTIONAL: URL of the page that Vault should redirect the user to when logging out of Vault. By default, Vault will redirect to a static page with a logout message. Note that this is a static redirect and Single Logout (SLO) is not currently supported.
Request Binding The type of request binding that your IdP is expecting the SP (Vault) to use. Vault supports both HTTP-Post and HTTP-Redirect binding.
SP-Initiated Request URL Request URL is where SP (Vault) initiated SAML authentication requests are sent.
Federated User ID Obtained from the Identity Provider and is configured in the user profiles.

Enter IdP Information in Vault SAML Profile

You can begin configuring SSO without changing the way existing users log into Vault. The Vault SSO Login URL displays the ACS URL to give to your IdP. Note that the SAML profile cannot be activated until the entire SAML profile is validated.

To configure SSO on your domain, enter the following information into the SAML Profile.

SAML Version Set to 2.0
SAML User ID Type See About SAML ID User Types below.
SP Entity ID This value identifies Vault as an SP entity to the IdP.
Identity Provider Certificate File Obtained from your IdP. See table above.
Identity Provider Login URL Obtained from your IdP. See table above.
Identity Provider Logout URL Obtained from your IdP. See table above.
SP-Initiated Request URL Obtained from your IdP. See table above.
SP-Initiated Request Binding See About SP-Initiated Request Binding below.
Signature and Digest Binding See About Signature & Digest Algorithm below.
Signature and Digest Algorithm Specifies the hash algorithm used to sign SAML requests.
eSignature Authentication Context See About eSignature Authentication Context below. 
eSignature Authentication Pop-up See About eSignature Authentication below.
Identity Provider Button See Identity Provider Button below.

Register Vault as a Service Provider (SP) in Your IdP

Your IdP may need the following information:

Vault Public Certificate File Contains the public key information for Vault. Download Vault SSL Certificates.
SP Entity ID Unique name to identify Vault to your IdP.  This should be the name defined in the SP Entity ID.
Destination URL SAML ACS endpoint in Vault. This is the Vault SSO Login URL field displayed at the top of the Single Sign-On Settings page.
Postback URL This also uses the Vault SSO Login URL field.
Service Provider SAML Attributes Vault requires an attribute called “uid” for passing the Federated User ID  to be used for SSO. The value you pass depends on the SAML User ID Type setting you have chosen (Vault User Name or Federated ID).

About User ID Types

The two options are Vault User Name and Federated ID.

Vault User Name

Choose Vault User Name if you plan to store the Vault user names as an attribute in your IdP user directory, or if the Vault user names happen to exactly match your enterprise user names. Basically, this puts the burden on the IdP to map enterprise user names to vault user names.

Federated ID

Choose Federated ID if you plan to store enterprise user names in the Federated ID field on the Vault user profile.  This puts the burden on Vault to map from enterprise user names to vault user names.

Importing IdP Metadata

To simplify SSO profile configuration, you can import your Identity Provider metadata by either uploading an IdP Metadata XML file or importing it from your IdP directly.

To import IdP metadata:

  1. Open a SAML Profile.
  2. From the action menu, select Import IdP Metadata.
  3. To import IdP metadata by uploading an XML file, select Upload IdP Metadata and then choose a file.
  4. To import IdP metadata by specifying a URL, select Provide IdP Metadata URL then enter the location of the file.
  5. Click Continue. Vault validates the contents of the IdP Metadata XML and returns an error message if the information is invalid. If the information is valid, the SSO profile switches to Edit mode with the imported values reflected on the page.
  6. To complete the configuration, click Save.

The XML file structure is defined in the SAML specifications.

Exporting SP Metadata

To simplify SSO configuration, for ongoing maintenance, or to ensure the validity of the SP metadata, you can download and/or monitor the SP Metadata for an SSO profile.

To export SP metadata:

  1. Open a SAML Profile.
  2. From the action menu, select Export SP Metadata. The VaultSPMetadata.xml file is downloaded to your local file system.

Note that this returns the cached SP metadata which is refreshed every 30 minutes. It is refreshed immediately after the SSO profile is modified.

The SP metadata can also be retrieved by going directly to the location pointed to by the SP Metadata URL field. This allows the SP metadata to be fetched directly from a client application or command line utility such as cURL while using a HTTP GET request. This is useful when IdPs want to monitor and/or dynamically update the SP metadata in their configurations. HTTP status code 400 is returned if the SSO profile is incomplete or invalid.

The XML file structure is defined in the SAML specifications.

About Deep-Linking

The Identity Provider Login URL can be configured to support IdP-initiated SAML flows with deep-linking.

The configuration of IdP-initiated URLs supports an expression syntax based on Mustache templating framework. The documentation for Mustache defines the full language syntax. We do not constrain any available Mustache features in the template. However, the syntax listed below are the only requirements for configuring deep-linking in Vault.

Identity Provider Login URL Advanced Configuration

You can use the following expression syntax to customize the URL per your Identity Provider requirements.

Construct Description
{{relay_state}} This token will be replaced by the current URL at runtime and will be HTML encoded.
{{{relay_state}}} This token will be replaced by the current URL at runtime but will not be HTML encoded.
{{#url_encode}} {{/url_encode}} This function URL-encodes everything that is between the opening and closing tag.

Example Configuration (ADFS 2.0):

https://adfs.domain.com/adfs/ls/IdpInitiatedSignOn.aspx?RelayState={{#url_encode}}RPID={{#url_encode}}http://customer.vault.com{{/url_encode}}&RelayState={{{relay_state}}}{{/url_encode}}

Upon saving of the form, the expression syntax/grammar is parsed and validated. Validation errors are returned on the configuration page.

About SP-Initiated Request Binding

The two options are HTTP Post and HTTP Redirect.

Note: When using Exostar IdP, we recommend setting the SP-initiated request binding to HTTP Post.

HTTP Post (Default)

This uses POST-POST SAML binding. This type of binding must be supported by your IdP.

With this type of binding, Vault sends an HTTP Redirect message to the IdP containing an authentication request. The IdP returns a SAML response with an assertion to Vault via HTTP POST.

Processing Steps:

  1. The user requests access to a Vault resource. If the user is not logged-in, the request is redirected to the IdP for authentication.
  2. The IdP sends an HTML form back to the browser with a SAML request for authentication. The HTML form is automatically posted back to the IdP.
  3. If the user is not already logged-in to the IdP, or if reauthentication is required, the IdP asks the user for credentials and the user logs in to the IdP.
  4. The IdP’s SSO service returns an HTML form to the browser with a SAML response containing the authentication assertion and the “uid”  attribute containing the Federated ID or Vault ID (depending on configuration). The browser automatically posts the HTML form back to Vault.
  5. If the signature and assertion are valid, Vault establishes a session for the user and redirects the browser to the requested Vault resource.

HTTP Redirect

Select HTTP Redirect to use Redirect-POST SAML binding. This type of binding must be supported by your IdP.

With this type of binding, Vault sends an HTTP Redirect message to the IdP containing an authentication request. The IdP returns a SAML response with an assertion to Vault via HTTP Redirect.

Processing Steps:

  1. The user requests access to a Vault resource. If the user is not logged-in, the request is redirected to the IdP for authentication.
  2. Vault returns an HTTP redirect (code 302) containing a SAML request for authentication through the user’s browser to the IdP.
  3. If the user is not already logged-in to the IdP, or if reauthentication is required, the IdP asks the user for credentials and the user logs in to the IdP.
  4. The IdP’s SSO service returns an HTML form to the browser with a SAML response containing the authentication assertion and the “uid”  attribute containing the Federated ID or Vault ID (depending on configuration). The browser automatically posts the HTML form back to Vault.
  5. If the signature and assertion are valid, Vault establishes a session for the user and redirects the browser to the requested Vault resource.

About Signature & Digest Algorithm

This setting specifies the hash algorithm for generating and validating SAML signatures. The following options are available: SHA-1, SHA-256

  • SHA-256: This generates an almost unique, fixed-size 256-bit hash. This is the recommended for SSO authentication.
  • SHA-1: This produces a 160-bit hash value known as “Message Digest.”

About eSignature Authentication Context

When configuring your IdP, verify that the setting to enable forcing authentication on SAML requests is on. For example, using Okta’s “Template SAML 2.0,” you must select the Force Authentication checkbox. 

There is a known issue which prevents users from completing eSignatures with their SAML identity providers though an iFrame using some browsers. You can avoid this issue by enabling third-party cookies or configuring the eSignature flow to complete through a pop-up by selecting the Authenticate SAML eSignatures in a pop-up window rather than an iFrame option. Note that this option only affects document eSignatures.

eSignature Authentication Context

The two options are None and PasswordProtectedTransport.

Select PasswordProtectedTransport if your SSO infrastructure is using Integrated Windows Authentication (IWA). This option configures the authentication context used by eSignature SP-initiated flow.

Once enabled, the following XML is added to the SAML request during eSignature SP-initiated flow:

<samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Comparison="exact">
<saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

eSignature Authentication Pop-Up

By default, Vault uses iFrames for SAML eSignature flow.

If your IdP does not support rendering of authentication screens inside an iFrame, select this checkbox to authenticate SAML eSignatures in an external pop-up window. This may simplify integrations with IdPs like Exostar and the latest version of PingFederate.

Known Issue for Internet Explorer™ 11

In order for eSignature Authentication to function properly with Internet Explorer™ (IE11), you must add the following domains to Internet Explorer’s™ Trusted sites configuration:

Domain Example
Auth https://veevaauth.vaultdev.com
Vault https://veeva.vaultdev.com
IdP https://veeva.okta.com

This issue only affects users with Internet Explorer™ 11 (IE11). If you experience this issue, we suggest you try another browser.

About SAML Response Signing

Vault SAML SSO requires that the entire SAML Response is signed. The SAML Assertion signature in the response is not validated and not required by Vault SAML SSO, but will not generate an error if your IdP decides to provide an additional signature in the assertion.

Identity Provider Button

The Identity Provider Button setting allows you to add a custom login button to your login page. This is ideal for customers with multiple Vault security policies. It provides Vault users with the option to log into Vault with their username and password or click the custom login button to log into Vault through their IdP.

When configuring multiple SSO profiles, Vault will display a logo for each active profile.

To add an Identity Provider Button to your login page:

  1. Click Add Custom Login Button to display the settings.
  2. Click Choose Logo Image and select an image to display on the button. The file format must be PNG, JPG, or GIF. The file size cannot be greater than 500KB. The image size cannot be greater than 400 x 100 pixels. Padding or margins around the image are not necessary - the image will be centered vertically in the button to the right of “Log in with”. For best results, the aspect ratio of the logo should be 4:1 or less. Typically, the image selected is your company logo or that of your IdP.
  3. Click Button Color and select a color for the button background.
  4. Click Border Color and select a color for the button border.
  5. Click Text Color and select a color for the “Log in with” text.
  6. Click Save. The Button Preview will be displayed on the page and on the Vault login page for your domain.