Configuring SAML Profiles

In order to use SAML for SSO and electronic signing, 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. Learn more about Supported IdPs/AS for Vault Products.

You can configure two profile types: Single Sign-on Profile and eSignature Profile. The Single Sign-on Profile is required for SSO login. The eSignature Profile is optional, used specifically for electronically signing documents and object records via SAML. If no eSignature Profile is configured in a Security Policy, the Single Sign-on Profile is used for both SSO login and eSignature. One Single Sign-on Profile and one eSignature Profile can be associated with the same Security Policy.

To create a SAML profile:

1. Ensure you have SSO Settings: Read and SSO Settings: Write access to Settings > SAML Profiles.
2. Go to Admin > Settings > SAML Profiles.
3. Click Create. Select either Single Sign-on Profile or eSignature Profile.
4. Enter a Label and Name for the profile.
5. Complete the SAML Profile configuration.
6. 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. If the IdP replaces or updates their certificate, you must update the SAML profile with a new certificate. See Importing IdP Metadata.

Identity Provider Login URL

For Single Sign-on Profile only. 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: For Single Sign-on Profile only. 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. 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 SAML Profile without changing the way existing users log into Vault or use eSignatures. The Vault SSO Login URL displays the ACS URL to give to your IdP. The SAML profile cannot be activated until the entire SAML profile is validated.

To configure a profile 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.

SP Entity ID

This value identifies Vault as an SP entity to the IdP.

Identity Provider Certificate File

Obtained from your IdP.

Identity Provider Login URL, Identity Provider Logout URL

For Single Sign-on Profile only. Obtained from your IdP.

SP-Initiated Request URL

Obtained from your IdP.

SP-Initiated Request Binding

See About SP-Initiated Request Binding.

SP Certificate

See About SP Certificate.

Signature and Digest Binding

See About Signature & Digest Algorithm.

Signature and Digest Algorithm

Specifies the hash algorithm used to sign SAML requests.

eSignature Authentication Context, eSignature Authentication Pop-up

See About eSignature Authentication Context.

Identity Provider Button

For Single Sign-on Profile only. See Identity Provider Button (Single Sign-on Profiles).

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 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 Actions 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 and then enter the location of the file. This URL must use the HTTPS protocol.
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 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 configuration for ongoing maintenance or to ensure the validity of the SP metadata, you can download and/or monitor the SP Metadata for a profile.

To export SP metadata:

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

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 profile is incomplete or invalid.

The XML file structure is defined in the SAML specifications.

About Deep-Linking (Single Sign-on Profiles)

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 Mustache documentation 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.

{{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 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 for both Single Sign-on Profiles and eSignature Profiles.

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 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 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 SP Certificates

Vault uses the SP Certificate to sign SAML Requests. All Vaults use the same signing certificate which is periodically renewed. Once the certificate is rolled over, Vault automatically updates all SAML Profiles to use the new certificate. Customers are notified ahead of time about the upcoming certificate rollover. The previous certificate is still available for a period of time known as the rollover period. During this time, you can switch between new and previous certificates if needed. Once the rollover period passes, the new certificate becomes the only active certificate on the SAML Profile.

To manage SAML signing certificates:

1. Navigate to Settings > SAML Profiles and select a profile.
2. Click the Edit button.
3. Select the checkbox next to the applicable certificate. If the current certificate is the only one available, the certificate is read-only and you can download it. If two certificates are available, you are in the certificate rollover period and should select the new certificate if possible. See Vault Certificates.
4. Optional: To download the certificate containing the public key, click the download icon next to the certificate.
5. Click Save to activate the selected certificate.

About Signature & Digest Algorithm

This setting specifies the hash algorithm for generating and validating SAML signatures. The following options are available:

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. This option only affects document eSignatures.

eSignature Authentication Context

The two options are None and PasswordProtectedTransport.

Select PasswordProtectedTransport if your 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 Explore (IE11), you must add the following domains to the trusted sites configuration:

Auth

https://veevaauth.vaultdev.com

Vault

https://veeva.vaultdev.com

IdP

https://veeva.okta.com

This issue only affects users with IE11. If you experience this issue, we suggest you try another browser.

About SAML Response Signing

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

Identity Provider Button (Single Sign-on Profiles)

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.