HashiConf 2024 Now streaming live from Boston! Attend for free
Vault
Vault Home

Use Active Directory Federation Services for SAML

Enterprise

Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.

Configure your Vault instance to work with Active Directory Federation Services (AD FS) and use AD FS accounts for SAML authentication.

Before you start

  • You must have Vault Enterprise or HCP Vault v1.15.5+.
  • You must be running AD FS on Windows Server.
  • You must have a SAML plugin enabled.
  • You must have a Vault admin token. If you do not have a valid admin token, you can generate a new token in the Vault GUI or using vault token create with the Vault CLI.

Step 1: Enable the SAML authN method for Vault

  1. Set the VAULT_ADDR environment variable to your Vault instance URL. For example:

    $ export VAULT_ADDR="https://myvault.example.com:8200"

  2. Set the VAULT_TOKEN environment variable with your admin token:

    $ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

  3. Enable the SAML plugin. Use the -namespace flag to enable the plugin under a specific namespace. For example:

    $ vault -namespace=ns_admin auth enable saml

Step 2: Create a new relying party trust in AD

  1. Open your Windows Server UI.

  2. Go to the Server Manager screen.

  3. Click Tools and select AD FS Management.

  4. Right-click Relying Party Trusts and select Add Relying Party Trust....

  5. Follow the prompts to create a new party trust with the following settings:

    OptionSetting
    Claims awarechecked
    Enter data about relying party manuallychecked
    Display name"Vault"
    CertificatesNone
    Enable support for the SAML 2.0 WebSSO protocolchecked
    SAML callback URLCallback endpoint for your SAML plugin
    Relying party trust identifierAny meaningful, unique string. For example "VaultIdentifier"
    Access control policyAny valid policy or Permit everyone
    Configure claims issuance policy for this applicationchecked

Tip

The callback endpoint for your SAML plugin is:

https://${VAULT_ADDRESS}/v1/<NAMESPACE>/<MOUNT_PATH>/auth/<PLUGIN_NAME>/callback

For example, if you mounted the plugin under the ns_admin namespace on the path org/security, the callback endpoint URL would be:

https://${VAULT_ADDRESS}/v1/ns_admin/auth/org/security/saml/callback

Step 3: Configure the claim issuance policy in AD

  1. Open your Windows Server UI.

  2. Go to the Server Manager screen.

  3. Click Tools and select AD FS Management.

  4. Right-click your new Relying Party Trust entry and select Edit Claim Issuance Policy....

  5. Click Add Rule... and follow the prompts to create a new Transform Claim Rule with the following settings:

    OptionSetting
    Send LDAP Attributes as Claimsselected
    Rule nameAny meaningful string (e.g., "Vault SAML Claims")
    Attribute storeActive Directory.

  6. Complete the LDAP attribute array with the following settings:

    LDAP attributeOutgoing claim type
    E-Mail-AddressesName ID
    E-Mail-AddressesE-Mail Address
    Token-Groups - Unqualified Namesgroups or Group

Step 4: Update the SAML signature in AD

  1. Open a PowerShell terminal on your Windows server.

  2. Set the SAML signature for your relying party trust identifier to false:

    Set-ADFSRelyingPartyTrust `
 -TargetName "<RELYING_PARTY_TRUST_IDENTIFIER>" `
 -SignedSamlRequestsRequired $false

    For example:

    Set-ADFSRelyingPartyTrust `
 -TargetName "MyVaultIdentifier" `
 -SignedSamlRequestsRequired $false

Step 5: Create a default AD FS role in Vault

Use the Vault CLI to create a default role for users authenticating with AD FS where:

$ vault write <SAML_PLUGIN_PATH>/role/<VAULT_ROLE>  \
    bound_subjects="<DOMAIN_LIST>"                  \
    bound_subjects_type="glob"                      \
    groups_attribute=<GROUP_ATTRIBUTES_REF>         \
    bound_attributes=groups="<AD_GROUP_LIST>"       \
    token_policies="default"                        \
    ttl="1h"

For example:

$ vault write auth/saml/role/adfs-default             \
    bound_subjects="*@example.com,*@ext.example.com"  \
    bound_subjects_type="glob"                        \
    groups_attribute=groups                           \
    bound_attributes=groups="VaultAdmin,VaultUser"    \
    token_policies="default"                          \
    ttl="1h"

Step 6: Configure the SAML plugin in Vault

Use the Vault CLI to finish configuring the SAML plugin where:

  • SAML_PLUGIN_PATH is the full path to your SAML plugin: <NAMESPACE>/auth/<MOUNT_PATH>/<PLUGIN_NAME>.
  • VAULT_ROLE is the name of your new AD FS role in Vault.
  • TRUST_IDENTIFIER is the ID of your new relying party trust in AD FS.
  • SAML_CALLBACK_URL is the callback endpoint for your SAML plugin: http://${VAULT_ADDR}/<NAMESPACE>/auth/<MOUNT_PATH>/<PLUGIN_NAME>/callback.
  • ADFS_URL is the discovery URL for your AD FS instance.
  • METADATA_FILE_PATH is the path on your AD FS instance to the federation metadata file.
$ vault write <SAML_PLUGIN_PATH>/config \
    default_role="<VAULT_ROLE>"         \
    entity_id="<TRUST_IDENTIFIER>"      \
    acs_urls="<SAML_CALLBACK_URL>       \
    idp_metadata_url="<AD FS_URL>/<METADATA_FILE_PATH>"

For example:

$ vault write ns_admin/auth/org/security/saml/config                    \
  default_role="adfs-default"                                           \
  entity_id="MyVaultIdentifier"                                         \
  acs_urls="${VAULT_ADDR}/v1/ns_admin/auth/org/security/saml/callback"  \
  idp_metadata_url="https://adfs.example.com/metadata/2007-06/federationmetadata.xml"

Next steps

Edit this page on GitHub