# 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](/en/lr/13977/). 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](/en/lr/52437/).

You can configure two profile types: [_Single Sign-on Profile_](/en/lr/13977/) and [_eSignature Profile_](/en/lr/14045/#why-do-esignatures-prompt-for-multi-factor-authentication). 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 a Security Profile with _Admin: Domain Administration: SSO Settings: Read_ and _Admin: Domain Administration: SSO Settings: Edit_ permissions.
2. Navigate to **Admin > Settings > SAML Profiles**.
3. Click **Create**. 
4. Select either **Single Sign-on Profile** or **eSignature Profile**.
5. Enter a **Label** and **Name** for the profile.
6. Optional: Set the **Status** to **Active** or **Inactive**. SAML profiles are created in **Inactive** status by default.
7. Optional: Enter a **Description** of the SAML profile.
8. Based on your selection, complete the **SAML Profile** configuration for a _Single Sign-on Profile_ or _eSignature Profile_. See the sections below in this article for more information.
9. Click **Save**.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: You can inactivate a SAML profile that is in use by security policies; however, you cannot assign the inactive SAML profile to a new or existing security policy. You can assign active security policies that reference an inactive SAML profile to new users.</p>
    </div>
  </div>
</div>



## Obtain Information from your Identity Provider (IdP) {#obtain-info}

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](/en/lr/43346/#importingidpmetadata).

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](/en/lr/43346/#aboutdeeplinking).

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 {#enter}

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](/en/lr/43346/#userID).

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

Identity Provider Certificate File
: [Obtained from your IdP](/en/lr/43346/#obtain-info).

Identity Provider Login URL, Identity Provider Logout URL
: For **Single Sign-on Profile** only. [Obtained from your IdP](/en/lr/43346/#obtain-info).

SP-Initiated Request URL
: [Obtained from your IdP](/en/lr/43346/#obtain-info).

SP-Initiated Request Binding
: See [About SP-Initiated Request Binding](/en/lr/43346/#spbinding).

SP Certificate
: See [About SP Certificate](/en/lr/43346/#spcert).

Signature and Digest Binding
: See [About Signature & Digest Algorithm](/en/lr/43346/#about_signature_and_digest_binding).

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](/en/lr/43346/#aboutconfigesigs).

Identity Provider Button
: For **Single Sign-on Profile** only. See [Identity Provider Button (Single Sign-on Profiles)](/en/lr/43346/#IDP-Login-Button).

## Register Vault as a Service Provider (SP) in Your IdP {#register}

Your IdP may need the following information:

Vault Public Certificate File
: Contains the public key information for Vault. [Download Vault SSL Certificates](/en/lr/18270/).

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 {#userID}

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 {#importingidpmetadata}

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 <a class="external-link " href="https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf" target="_blank" rel="noopener">SAML specifications<i class="fa fa-external-link" aria-hidden="true"></i></a>.

## 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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: The cached SP metadata refreshes every 30 minutes or immediately after the profile is modified.</p>
    </div>
  </div>
</div>



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 <a class="external-link " href="https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf" target="_blank" rel="noopener">SAML specifications<i class="fa fa-external-link" aria-hidden="true"></i></a>.

## About Deep-Linking (Single Sign-on Profiles) {#aboutdeeplinking}

The Identity Provider Login URL can be configured to support IdP-initiated SAML flows with [deep-linking](/en/lr/13982/#aboutdeeplinking).

The configuration of IdP-initiated URLs supports an expression syntax based on **Mustache** templating framework. The <a class="external-link " href="https://mustache.github.io/" target="_blank" rel="noopener">Mustache documentation<i class="fa fa-external-link" aria-hidden="true"></i></a> 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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: Vault continues to support the legacy RelayState parameter <code class="language-plaintext highlighter-rouge">#(relayState)</code>. However, we encourage you to utilize the constructs defined in the table above.</p>
    </div>
  </div>
</div>



## About SP-Initiated Request Binding {#spbinding}

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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: SAML specifications require that POST responses be digitally signed.</p>
    </div>
  </div>
</div>



### 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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: New Vault domains provisioned as of Vault v13.0 will instruct the IdP to use HTTP Post for delivering the SAML response instead.</p>
    </div>
  </div>
</div>



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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: SAML specifications require that POST responses be digitally signed. The response delivered by Redirect will contain a <code class="language-plaintext highlighter-rouge">signature</code> and <code class="language-plaintext highlighter-rouge">sigalg</code> parameter.</p>
    </div>
  </div>
</div>



## About SP Certificates {#spcert}

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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: The SP certificate saved on the SAML Profile is immediately used to sign SAML Requests. All certificates are exposed in the SP Metadata.</p>
    </div>
  </div>
</div>



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](/en/lr/18270/).
  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 {#about_signature_and_digest_binding}

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 {#aboutconfigesigs}

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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: eSignature Authentication requires SP-Initiated SAML mode.</p>
    </div>
  </div>
</div>



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</a></a> {#known_issues_for_windows_7_ie11}

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.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: SAML responses are validated even if the IdP certificate has expired. Ensure the IdP certificate used to sign the SAML response is active.</p>
    </div>
  </div>
</div>



## Identity Provider Button (Single Sign-on Profiles) {#IDP-Login-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.