vault Login MFA FAQ Commonly questions about Vault login MFA and multi factor authentication layout docs This FAQ section contains frequently asked questions about the Login MFA feature page title Login MFA FAQ

Answer:
---
layout: docs
page_title: Login MFA FAQ
description: >-
  Commonly questions about Vault login MFA and multi-factor authentication.
---

# Login MFA FAQ

This FAQ section contains frequently asked questions about the Login MFA feature.

- [Q: What MFA features can I access if I upgrade to Vault version 1.10?](#q-what-mfa-features-can-i-access-if-i-upgrade-to-vault-version-1-10)
- [Q: What are the various MFA workflows that are available to me as a Vault user as of Vault version 1.10, and how are they different?](#q-what-are-the-various-mfa-workflows-that-are-available-to-me-as-a-vault-user-as-of-vault-version-1-10-and-how-are-they-different)
- [Q: What is the Legacy MFA feature?](#q-what-is-the-legacy-mfa-feature)
- [Q: Will HCP Vault Dedicated support MFA?](#q-will-hcp-vault-support-mfa)
- [Q: What is Single-Phase MFA vs. Two-Phase MFA?](#q-what-is-single-phase-mfa-vs-two-phase-mfa)
- [Q: Are there new MFA API endpoints introduced as part of the new Vault version 1.10 MFA for login functionality?](#q-are-there-new-mfa-api-endpoints-introduced-as-part-of-the-new-vault-version-1-10-mfa-for-login-functionality)
- [Q: How do MFA configurations differ between the Login MFA and Step-up Enterprise MFA?](#q-how-do-mfa-configurations-differ-between-the-login-mfa-and-step-up-enterprise-mfa)
- [Q: What are the ways to configure the various MFA workflows?](#q-what-are-the-ways-to-configure-the-various-mfa-workflows)
- [Q: What MFA mechanism is used with the different MFA workflows in Vault version 1.10?](#q-which-mfa-mechanism-is-used-with-the-different-mfa-workflows-in-vault-version-1-10)
- [Q: Are namespaces supported with the MFA workflows that Vault has as of Vault version 1.10?](#q-are-namespaces-supported-with-the-mfa-workflows-that-vault-has-as-of-vault-version-1-10)
- [Q: I use the Vault Agent. Does MFA pose any challenges for me?](#q-i-use-the-vault-agent-does-mfa-pose-any-challenges-for-me)
- [Q: I am a Step-up Enterprise MFA user using MFA for login. Should I migrate to the new Login MFA?](#q-i-am-a-step-up-enterprise-mfa-user-using-mfa-for-login-should-i-migrate-to-the-new-login-mfa)
- [Q: I am a Step-up Enterprise MFA user using MFA for login. What are the steps to migrate to Login MFA?](#q-i-am-a-step-up-enterprise-mfa-user-using-mfa-for-login-what-are-the-steps-to-migrate-to-login-mfa)

### Q: what MFA features can i access if i upgrade to Vault version 1.10?

Vault supports Step-up Enterprise MFA as part of our Enterprise edition. The Step-up Enterprise MFA provides MFA on login, or for step-up access to sensitive resources in Vault using ACL and Sentinel policies, and is configurable through the CLI/API.

Starting with Vault version 1.10, Vault Community Edition provides [MFA on login](/vault/docs/auth/login-mfa) only. This is also available with Vault Enterprise and configurable through the CLI/API.

The Step-up Enterprise MFA will co-exist with the newly introduced Login MFA starting with Vault version 1.10.

### Q: what are the various MFA workflows that are available to me as a Vault user as of Vault version 1.10, and how are they different?

| MFA workflow                                   | What does it do?                                                                                | Who manages the MFA?              | Community vs. Enterprise Support    |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------- |
| [Login MFA](/vault/docs/auth/login-mfa)              | MFA in Vault Community Edition provides MFA on login. CLI, API, and UI-based login are supported.                                                                                | MFA is managed by Vault           | Supported in Vault Community Edition        |
| [Okta Auth MFA](/vault/docs/auth/okta#mfa)           | This is MFA as part of [Okta Auth method](/vault/docs/auth/okta) in Vault Community Edition, where MFA is enforced by Okta on login. MFA must be satisfied for authentication to be successful. This is different from the Okta MFA method used with Login MFA and Step-up Enterprise MFA. CLI/API login are supported. | MFA is managed externally by Okta | Supported in Vault Community Edition        |
| [Step-up Enterprise MFA](/vault/docs/enterprise/mfa) | MFA in Vault Enterprise provides MFA for login and for step-up access to sensitive resources in Vault. Supports CLI/API based login, and ACL/Sentinel policies.                                                                                | MFA is managed by Vault           | Supported in Vault Enterprise |

~> **Note**: [The Legacy MFA](/vault/docs/v1.10.x/auth/mfa) is a **deprecated** MFA workflow in Vault Community Edition. Refer [here](#q-what-is-the-legacy-mfa-feature) for more details.

### Q: what is the legacy MFA feature?

[Legacy MFA](/vault/docs/v1.10.x/auth/mfa) is functionality that was available in Vault Community Edition, prior to introducing MFA in the Enterprise version. This is now a deprecated feature. Please see the [Vault Feature Deprecation Notice and Plans](/vault/docs/deprecation) for detailed product plans around deprecated features. We plan to remove Legacy MFA in 1.11.

### Q: will HCP Vault Dedicated support MFA?

Yes, HCP Vault Dedicated will support MFA across all tiers and offering as part of the April 2022 release.

### Q: what is Single-Phase MFA vs. Two-Phase MFA?

- **Single-Phase MFA:** This is a single request mechanism where the required MFA information, such as MFA method ID, is provided via the X-Vault-MFA header in a single MFA request that is used to authenticate into Vault.

~> **Note**: If the configured MFA methods need a passcode, it needs to be provided in the request, such as in the case of TOTP or Duo.
If the configured MFA methods, such as PingID, Okta, or Duo, do not require a passcode and have out of band mechanisms for verifying the extra factor, Vault will send an inquiry to the other service's APIs to determine whether the MFA request has yet been verified.

- **Two-Phase MFA:** This is a two-request MFA method that is more conventionally used.
  - The MFA passcode required for the configured MFA method is not provided in a header of the login request that is MFA-restricted. Instead, the user first authenticates to the auth method, and on successful authentication to the auth method, an MFA requirement is returned to the user. The MFA requirement contains the MFA RequestID and constraints applicable to the MFA as configured by the operator.
  - The user then must make a second request to the new endpoint `sys/mfa/validate`, providing the MFA RequestID in the request, and an MFA payload which includes the MFA methodIDs passcode (if applicable). If MFA validation passes, the new Vault token will be persisted and returned to the user in the response, just like a regular Vault token created using a non-MFA-restricted auth method.

### Q: are there new MFA API endpoints introduced as part of the new Vault version 1.10 MFA for login functionality?

Yes, this feature adds the following new MFA configuration endpoints: `identity/mfa/method`, `identity/mfa/login-enforcement`, and `sys/mfa/validate`. Refer to the [documentation](/vault/api-docs/secret/identity/mfa/duo) for more details.

### Q: how do MFA configurations differ between the login MFA and step-up enterprise MFA?

All MFA methods supported with the Step-up Enterprise MFA are supported with the Login MFA, but they use different API endpoints:

- Step-up Enterprise MFA: `sys/mfa/method/:type/:/name`
- Login MFA: `identity/mfa/method/:type`

There are also two differences in how methods are defined in the two systems.
The Step-up Enterprise MFA expects the method creator to specify a name for the method; Login MFA does not, and instead returns an ID when a method is created.
The Step-up Enterprise MFA uses the combination of mount accessors plus a `username_format` template string, whereas in Login MFA, these are combined into a single field `username_format`, which uses the same identity [templating format](/vault/docs/concepts/policies#templated-policies) as used in policies.

### Q: what are the ways to configure the various MFA workflows?

| MFA workflow                                   | Configuration methods                                                                     | Details                                                                                |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Login MFA](/vault/docs/auth/login-mfa)              | CLI/API. The UI does not support the configuration of Login MFA as of Vault version 1.10. | Configured using the `identity/mfa/method` endpoints, then passing those method IDs to the `identity/mfa/login-enforcement` endpoint. MFA methods supported: TOTP, Okta, Duo, PingID.                                                                                |
| [Okta Auth MFA](/vault/docs/auth/okta)               | CLI/API                                                                                | MFA methods supported: [TOTP](https://help.okta.com/en/prod/Content/Topics/Security/mfa-totp-seed.htm) , [Okta Verify Push](https://help.okta.com/en/prod/Content/Topics/Mobile/ov-admin-config.htm). |
| [Step-up Enterprise MFA](/vault/docs/enterprise/mfa) | CLI/API                                                                                | [Configured](/vault/api-docs/system/mfa) using the `sys/mfa/method` endpoints and by referencing those methods in policies. MFA Methods supported: TOTP, Okta, Duo, PingID                                                                                |

### Q: which MFA mechanism is used with the different MFA workflows in Vault version 1.10?

| MFA workflow                                   | UI        | CLI/API                                                                                | Single-Phase                | Two-Phase                   |
| ---------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------- |
| [Login MFA](/vault/docs/auth/login-mfa)              | Supported | Supported. You can select single-phase MFA by supplying the X-Vault-MFA header. In the absence of this header, the Two- Phase MFA is used | N/A                         | Supported                   |
| [Okta Auth MFA](/vault/docs/auth/okta)               | N/A       | N/A                                                                                | MFA is not managed by Vault | MFA is not managed by Vault |
| [Step-up Enterprise MFA](/vault/docs/enterprise/mfa) | N/A       | Supported                                                                                | Supported                   | N/A                         |

### Q: are namespaces supported with the MFA workflows that Vault has as of Vault version 1.10?

The Step-up Enterprise MFA configurations can only be configured in the root [namespace](/vault/docs/enterprise/mfa#namespaces), although they can be referenced in other namespaces via the policies.
The Login MFA supports namespaces awareness. Users will need a Vault Enterprise license to user or configure Login MFA with namespaces. MFA method configurations can be defined per namespace with Login MFA, and used in enforcements defined in that namespace and its children. Everything operates in the root namespace in Vault Community Edition. MFA login enforcements can also be defined per namespace, and applied to that namespace and its children.

### Q: i use the Vault agent. does MFA pose any challenges for me?

The Vault Agent should not use MFA to authenticate to Vault; it should be able to relay requests with MFA-related headers to Vault successfully.

### Q: i am a step-up enterprise MFA user using MFA for login. should i migrate to the new login MFA?

If you are currently using Enterprise MFA, evaluate your MFA specific use cases to determine whether or not you should migrate to [Login MFA](/vault/docs/auth/login-mfa).

Here are some considerations:

- If you use the Step-up Enterprise MFA for login (with Sentinel EGP), you may find value in the simpler Login MFA workflow. We recommend that you to test this out to evaluate if this meets all your requirements.
- If you use the Step-up Enterprise MFA for more than login, please be aware that the new MFA workflow only supports the login use case. You will still need to use the Step-up Enterprise MFA for non-login use cases.

### Q: i am a step-up enterprise MFA user using MFA for login. what are the steps to migrate to login MFA?

Refer to the question [Q: I am a Step-up Enterprise MFA user using MFA for login. Should I migrate to the new Login MFA?](#q-i-am-a-step-up-enterprise-mfa-user-using-mfa-for-login-should-i-migrate-to-the-new-login-mfa) to evaluate whether or not you should migrate.

If you wish to migrate to Login MFA, follow these steps and guidelines to migrate successfully.

1. First, create new MFA methods using the `identity/mfa/method` endpoints. These should mostly use the same fields as the MFA methods you defined using the `sys/mfa` method while keeping the following in mind:

   -the new endpoints yield an ID instead of allowing you to define a name

   -the new non-TOTP endpoints have a username_format field instead of username_format+mount_accessor fields; see [Templated Policies](/vault/docs/concepts/policies#templated-policies) for the username_format format.

1. Instead of writing sentinel EGP rules to require that logins use MFA, use the `identity/mfa/login_enforcement` endpoint to specify the MFA methods.

layout  docs page title  Login MFA FAQ description       Commonly questions about Vault login MFA and multi factor authentication         Login MFA FAQ  This FAQ section contains frequently asked questions about the Login MFA feature      Q  What MFA features can I access if I upgrade to Vault version 1 10    q what mfa features can i access if i upgrade to vault version 1 10     Q  What are the various MFA workflows that are available to me as a Vault user as of Vault version 1 10  and how are they different    q what are the various mfa workflows that are available to me as a vault user as of vault version 1 10 and how are they different     Q  What is the Legacy MFA feature    q what is the legacy mfa feature     Q  Will HCP Vault Dedicated support MFA    q will hcp vault support mfa     Q  What is Single Phase MFA vs  Two Phase MFA    q what is single phase mfa vs two phase mfa     Q  Are there new MFA API endpoints introduced as part of the new Vault version 1 10 MFA for login functionality    q are there new mfa api endpoints introduced as part of the new vault version 1 10 mfa for login functionality     Q  How do MFA configurations differ between the Login MFA and Step up Enterprise MFA    q how do mfa configurations differ between the login mfa and step up enterprise mfa     Q  What are the ways to configure the various MFA workflows    q what are the ways to configure the various mfa workflows     Q  What MFA mechanism is used with the different MFA workflows in Vault version 1 10    q which mfa mechanism is used with the different mfa workflows in vault version 1 10     Q  Are namespaces supported with the MFA workflows that Vault has as of Vault version 1 10    q are namespaces supported with the mfa workflows that vault has as of vault version 1 10     Q  I use the Vault Agent  Does MFA pose any challenges for me    q i use the vault agent does mfa pose any challenges for me     Q  I am a Step up Enterprise MFA user using MFA for login  Should I migrate to the new Login MFA    q i am a step up enterprise mfa user using mfa for login should i migrate to the new login mfa     Q  I am a Step up Enterprise MFA user using MFA for login  What are the steps to migrate to Login MFA    q i am a step up enterprise mfa user using mfa for login what are the steps to migrate to login mfa       Q  what MFA features can i access if i upgrade to Vault version 1 10   Vault supports Step up Enterprise MFA as part of our Enterprise edition  The Step up Enterprise MFA provides MFA on login  or for step up access to sensitive resources in Vault using ACL and Sentinel policies  and is configurable through the CLI API   Starting with Vault version 1 10  Vault Community Edition provides  MFA on login   vault docs auth login mfa  only  This is also available with Vault Enterprise and configurable through the CLI API   The Step up Enterprise MFA will co exist with the newly introduced Login MFA starting with Vault version 1 10       Q  what are the various MFA workflows that are available to me as a Vault user as of Vault version 1 10  and how are they different     MFA workflow                                     What does it do                                                                                Who manages the MFA                 Community vs  Enterprise Support                                                                                Login MFA   vault docs auth login mfa                 MFA in Vault Community Edition provides MFA on login  CLI  API  and UI based login are supported                                                                                MFA is managed by Vault             Supported in Vault Community Edition             Okta Auth MFA   vault docs auth okta mfa              This is MFA as part of  Okta Auth method   vault docs auth okta  in Vault Community Edition  where MFA is enforced by Okta on login  MFA must be satisfied for authentication to be successful  This is different from the Okta MFA method used with Login MFA and Step up Enterprise MFA  CLI API login are supported    MFA is managed externally by Okta   Supported in Vault Community Edition             Step up Enterprise MFA   vault docs enterprise mfa    MFA in Vault Enterprise provides MFA for login and for step up access to sensitive resources in Vault  Supports CLI API based login  and ACL Sentinel policies                                                                                MFA is managed by Vault             Supported in Vault Enterprise         Note     The Legacy MFA   vault docs v1 10 x auth mfa  is a   deprecated   MFA workflow in Vault Community Edition  Refer  here   q what is the legacy mfa feature  for more details       Q  what is the legacy MFA feature    Legacy MFA   vault docs v1 10 x auth mfa  is functionality that was available in Vault Community Edition  prior to introducing MFA in the Enterprise version  This is now a deprecated feature  Please see the  Vault Feature Deprecation Notice and Plans   vault docs deprecation  for detailed product plans around deprecated features  We plan to remove Legacy MFA in 1 11       Q  will HCP Vault Dedicated support MFA   Yes  HCP Vault Dedicated will support MFA across all tiers and offering as part of the April 2022 release       Q  what is Single Phase MFA vs  Two Phase MFA       Single Phase MFA    This is a single request mechanism where the required MFA information  such as MFA method ID  is provided via the X Vault MFA header in a single MFA request that is used to authenticate into Vault        Note    If the configured MFA methods need a passcode  it needs to be provided in the request  such as in the case of TOTP or Duo  If the configured MFA methods  such as PingID  Okta  or Duo  do not require a passcode and have out of band mechanisms for verifying the extra factor  Vault will send an inquiry to the other service s APIs to determine whether the MFA request has yet been verified       Two Phase MFA    This is a two request MFA method that is more conventionally used      The MFA passcode required for the configured MFA method is not provided in a header of the login request that is MFA restricted  Instead  the user first authenticates to the auth method  and on successful authentication to the auth method  an MFA requirement is returned to the user  The MFA requirement contains the MFA RequestID and constraints applicable to the MFA as configured by the operator      The user then must make a second request to the new endpoint  sys mfa validate   providing the MFA RequestID in the request  and an MFA payload which includes the MFA methodIDs passcode  if applicable   If MFA validation passes  the new Vault token will be persisted and returned to the user in the response  just like a regular Vault token created using a non MFA restricted auth method       Q  are there new MFA API endpoints introduced as part of the new Vault version 1 10 MFA for login functionality   Yes  this feature adds the following new MFA configuration endpoints   identity mfa method    identity mfa login enforcement   and  sys mfa validate   Refer to the  documentation   vault api docs secret identity mfa duo  for more details       Q  how do MFA configurations differ between the login MFA and step up enterprise MFA   All MFA methods supported with the Step up Enterprise MFA are supported with the Login MFA  but they use different API endpoints     Step up Enterprise MFA   sys mfa method  type   name    Login MFA   identity mfa method  type   There are also two differences in how methods are defined in the two systems  The Step up Enterprise MFA expects the method creator to specify a name for the method  Login MFA does not  and instead returns an ID when a method is created  The Step up Enterprise MFA uses the combination of mount accessors plus a  username format  template string  whereas in Login MFA  these are combined into a single field  username format   which uses the same identity  templating format   vault docs concepts policies templated policies  as used in policies       Q  what are the ways to configure the various MFA workflows     MFA workflow                                     Configuration methods                                                                       Details                                                                                Login MFA   vault docs auth login mfa                 CLI API  The UI does not support the configuration of Login MFA as of Vault version 1 10    Configured using the  identity mfa method  endpoints  then passing those method IDs to the  identity mfa login enforcement  endpoint  MFA methods supported  TOTP  Okta  Duo  PingID                                                                                Okta Auth MFA   vault docs auth okta                  CLI API                                                                                MFA methods supported   TOTP  https   help okta com en prod Content Topics Security mfa totp seed htm     Okta Verify Push  https   help okta com en prod Content Topics Mobile ov admin config htm        Step up Enterprise MFA   vault docs enterprise mfa    CLI API                                                                                Configured   vault api docs system mfa  using the  sys mfa method  endpoints and by referencing those methods in policies  MFA Methods supported  TOTP  Okta  Duo  PingID                                                                                Q  which MFA mechanism is used with the different MFA workflows in Vault version 1 10     MFA workflow                                     UI          CLI API                                                                                Single Phase                  Two Phase                                                                                Login MFA   vault docs auth login mfa                 Supported   Supported  You can select single phase MFA by supplying the X Vault MFA header  In the absence of this header  the Two  Phase MFA is used   N A                           Supported                        Okta Auth MFA   vault docs auth okta                  N A         N A                                                                                MFA is not managed by Vault   MFA is not managed by Vault      Step up Enterprise MFA   vault docs enterprise mfa    N A         Supported                                                                                Supported                     N A                                Q  are namespaces supported with the MFA workflows that Vault has as of Vault version 1 10   The Step up Enterprise MFA configurations can only be configured in the root  namespace   vault docs enterprise mfa namespaces   although they can be referenced in other namespaces via the policies  The Login MFA supports namespaces awareness  Users will need a Vault Enterprise license to user or configure Login MFA with namespaces  MFA method configurations can be defined per namespace with Login MFA  and used in enforcements defined in that namespace and its children  Everything operates in the root namespace in Vault Community Edition  MFA login enforcements can also be defined per namespace  and applied to that namespace and its children       Q  i use the Vault agent  does MFA pose any challenges for me   The Vault Agent should not use MFA to authenticate to Vault  it should be able to relay requests with MFA related headers to Vault successfully       Q  i am a step up enterprise MFA user using MFA for login  should i migrate to the new login MFA   If you are currently using Enterprise MFA  evaluate your MFA specific use cases to determine whether or not you should migrate to  Login MFA   vault docs auth login mfa    Here are some considerations     If you use the Step up Enterprise MFA for login  with Sentinel EGP   you may find value in the simpler Login MFA workflow  We recommend that you to test this out to evaluate if this meets all your requirements    If you use the Step up Enterprise MFA for more than login  please be aware that the new MFA workflow only supports the login use case  You will still need to use the Step up Enterprise MFA for non login use cases       Q  i am a step up enterprise MFA user using MFA for login  what are the steps to migrate to login MFA   Refer to the question  Q  I am a Step up Enterprise MFA user using MFA for login  Should I migrate to the new Login MFA    q i am a step up enterprise mfa user using mfa for login should i migrate to the new login mfa  to evaluate whether or not you should migrate   If you wish to migrate to Login MFA  follow these steps and guidelines to migrate successfully   1  First  create new MFA methods using the  identity mfa method  endpoints  These should mostly use the same fields as the MFA methods you defined using the  sys mfa  method while keeping the following in mind       the new endpoints yield an ID instead of allowing you to define a name      the new non TOTP endpoints have a username format field instead of username format mount accessor fields  see  Templated Policies   vault docs concepts policies templated policies  for the username format format   1  Instead of writing sentinel EGP rules to require that logins use MFA  use the  identity mfa login enforcement  endpoint to specify the MFA methods


vault Use Active Directory Federation Services for SAML layout docs include alerts enterprise and hcp mdx Use Active Directory Federation Services AD FS as a SAML provider for Vault page title Use Active Directory Federation Services for SAML

Answer:
---
layout: docs
page_title: Use Active Directory Federation Services for SAML
description: >-
  Use Active Directory Federation Services (AD FS) as a SAML provider for Vault.
---

# Use Active Directory Federation Services for SAML

@include 'alerts/enterprise-and-hcp.mdx'

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](/vault/docs/auth/saml) 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`](/vault/docs/commands/token/create) with the Vault CLI.

## Step 1: Enable the SAML authN method for Vault

<Tabs>

<Tab heading="Vault CLI" group="cli">

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

   ```shell-session
   $ export VAULT_ADDR="https://myvault.example.com:8200"
   ```

1. Set the `VAULT_TOKEN` environment variable with your admin token:

   ```shell-session
   $ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
   ```

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

   ```shell-session
   $ vault -namespace=ns_admin auth enable saml
   ```

</Tab>

<Tab heading="Vault GUI" group="gui">

@include 'gui-instructions/enable-authn-plugin.mdx'

- Enable the SAML plugin:

    1. Select the **SAML** token.
    1. Set the mount path.
    1. Click **Enable Method**.

</Tab>

</Tabs>

## Step 2: Create a new relying party trust in AD

1. Open your Windows Server UI.

1. Go to the **Server Manager** screen.

1. Click **Tools** and select **AD FS Management**.

1. Right-click **Relying Party Trusts** and select **Add Relying Party Trust...**.

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

    | Option                                                | Setting
    | ----------------------------------------------------- | -------
    | Claims aware                                          | checked
    | Enter data about relying party manually               | checked
    | Display name                                          | "Vault"
    | Certificates                                          | None
    | Enable support for the SAML 2.0 WebSSO protocol       | checked
    | SAML callback URL                                     | Callback endpoint for your SAML plugin
    | Relying party trust identifier                        | Any meaningful, unique string. For example "VaultIdentifier"
    | Access control policy                                 | Any valid policy or  `Permit everyone`
    | Configure claims issuance policy for this application | checked

<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`

</Tip>

## Step 3: Configure the claim issuance policy in AD

1. Open your Windows Server UI.

1. Go to the **Server Manager** screen.

1. Click **Tools** and select **AD FS Management**.

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

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

    | Option                          | Setting
    | ------------------------------- | -------
    | Send LDAP Attributes as Claims  | selected
    | Rule name                       | Any meaningful string (e.g., "Vault SAML Claims")
    | Attribute store                 | `Active Directory`.

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

    | LDAP attribute                     | Outgoing claim type           |
    |------------------------------------|-------------------------------|
    | `E-Mail-Addresses`                 | `Name ID`                     |
    | `E-Mail-Addresses`                 | `E-Mail Address`              |
    | `Token-Groups - Unqualified Names` | `groups` or `Group`           |

## Step 4: Update the SAML signature in AD

1. Open a PowerShell terminal on your Windows server.

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

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

   For example:

  <CodeBlockConfig hideClipboard>

   ```powershell
   Set-ADFSRelyingPartyTrust `
    -TargetName "MyVaultIdentifier" `
    -SignedSamlRequestsRequired $false
   ```
  </CodeBlockConfig>

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

- `SAML_PLUGIN_PATH` is the full path (`<NAMESPACE>/MOUNT_PATH/NAME`) to your
  SAML plugin.
- `VAULT_ROLE` is the name of your new AD FS role. For example, `adfs-default`.
- `DOMAIN_LIST` is a comma separated list of target domains in Active Directory.
  For example: `*@example.com,*@ext.example.com`.
- `GROUP_ATTRIBUTES_REF` is:
    - `groups` if your LDAP token group is `groups`
    - `http://schemas.xmlsoap.org/claims/Group` if your LDAP token group is
      `Group`
- `AD_GROUP_LIST` is a comma separated list of Active Directory groups that
  will authenticate with SAML. For example: `VaultAdmin,VaultUser`.

```shell-session
$ 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:

<CodeBlockConfig hideClipboard>

```shell-session
$ 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"
```

</CodeBlockConfig>

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

```shell-session
$ 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:

<CodeBlockConfig hideClipboard>

```shell-session
$ 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"
```

</CodeBlockConfig>

## Next steps

- [Link your Active Directory groups to Vault](/vault/docs/auth/saml/link-vault-group-to-ad)
- [Troubleshoot your SAML + AD FS configuration](/vault/docs/auth/saml/troubleshoot-adfs)

layout  docs page title  Use Active Directory Federation Services for SAML description       Use Active Directory Federation Services  AD FS  as a SAML provider for Vault         Use Active Directory Federation Services for SAML   include  alerts enterprise and hcp mdx   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   vault docs auth saml  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    vault docs commands token create  with the Vault CLI        Step 1  Enable the SAML authN method for Vault   Tabs    Tab heading  Vault CLI  group  cli    1  Set the  VAULT ADDR  environment variable to your Vault instance URL  For    example         shell session      export VAULT ADDR  https   myvault example com 8200          1  Set the  VAULT TOKEN  environment variable with your admin token         shell session      export VAULT TOKEN  XXXXXXXX XXXX XXXX XXXX XXXXXXXXXXXX          1  Enable the SAML plugin  Use the   namespace  flag to enable the plugin under    a specific namespace  For example         shell session      vault  namespace ns admin auth enable saml           Tab    Tab heading  Vault GUI  group  gui     include  gui instructions enable authn plugin mdx     Enable the SAML plugin       1  Select the   SAML   token      1  Set the mount path      1  Click   Enable Method       Tab     Tabs        Step 2  Create a new relying party trust in AD  1  Open your Windows Server UI   1  Go to the   Server Manager   screen   1  Click   Tools   and select   AD FS Management     1  Right click   Relying Party Trusts   and select   Add Relying Party Trust        1  Follow the prompts to create a new party trust with the following settings         Option                                                  Setting                                                                             Claims aware                                            checked       Enter data about relying party manually                 checked       Display name                                             Vault        Certificates                                            None       Enable support for the SAML 2 0 WebSSO protocol         checked       SAML callback URL                                       Callback endpoint for your SAML plugin       Relying party trust identifier                          Any meaningful  unique string  For example  VaultIdentifier        Access control policy                                   Any valid policy or   Permit everyone        Configure claims issuance policy for this application   checked   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     Tip        Step 3  Configure the claim issuance policy in AD  1  Open your Windows Server UI   1  Go to the   Server Manager   screen   1  Click   Tools   and select   AD FS Management     1  Right click your new   Relying Party Trust   entry and select      Edit Claim Issuance Policy        1  Click   Add Rule      and follow the prompts to create a new   Transform    Claim Rule   with the following settings         Option                            Setting                                                       Send LDAP Attributes as Claims    selected       Rule name                         Any meaningful string  e g    Vault SAML Claims         Attribute store                    Active Directory    1  Complete the LDAP attribute array with the following settings         LDAP attribute                       Outgoing claim type                                                                                E Mail Addresses                     Name ID                               E Mail Addresses                     E Mail Address                        Token Groups   Unqualified Names     groups  or  Group                    Step 4  Update the SAML signature in AD  1  Open a PowerShell terminal on your Windows server   1  Set the SAML signature for your relying party trust identifier to  false          powershell    Set ADFSRelyingPartyTrust        TargetName   RELYING PARTY TRUST IDENTIFIER          SignedSamlRequestsRequired  false            For example      CodeBlockConfig hideClipboard         powershell    Set ADFSRelyingPartyTrust        TargetName  MyVaultIdentifier         SignedSamlRequestsRequired  false            CodeBlockConfig       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      SAML PLUGIN PATH  is the full path    NAMESPACE  MOUNT PATH NAME   to your   SAML plugin     VAULT ROLE  is the name of your new AD FS role  For example   adfs default      DOMAIN LIST  is a comma separated list of target domains in Active Directory    For example     example com   ext example com      GROUP ATTRIBUTES REF  is         groups  if your LDAP token group is  groups         http   schemas xmlsoap org claims Group  if your LDAP token group is        Group     AD GROUP LIST  is a comma separated list of Active Directory groups that   will authenticate with SAML  For example   VaultAdmin VaultUser       shell session   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    CodeBlockConfig hideClipboard      shell session   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         CodeBlockConfig        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      shell session   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    CodeBlockConfig hideClipboard      shell session   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         CodeBlockConfig        Next steps     Link your Active Directory groups to Vault   vault docs auth saml link vault group to ad     Troubleshoot your SAML   AD FS configuration   vault docs auth saml troubleshoot adfs


vault page title Set up SAML authN Use SAML authentication with Vault to authenticate Vault users with public keys or certificates and a SAML identity provider layout docs Set up SAML authentication

Answer:
---
layout: docs
page_title: Set up SAML authN
description: >-
  Use SAML authentication with Vault to authenticate Vault users with public
  keys or certificates and a SAML identity provider.
---

# Set up SAML authentication

@include 'alerts/enterprise-and-hcp.mdx'

The `saml` auth method allows users to authentication with Vault using their identity
within a [SAML V2.0](https://saml.xml.org/saml-specifications) identity provider.
Authentication is suited for human users by requiring interaction with a web browser.

## Authentication

<Tabs>

<Tab heading="Vault CLI">

The CLI login defaults to the `/saml` path. If this auth method was enabled at a
different path, specify `-path=/my-path` in the CLI.

```shell-session
$ vault login -method=saml role=admin

Complete the login via your SAML provider. Launching browser to:

    https://company.okta.com/app/vault/abc123eb9xnIfzlaf697/sso/saml?SAMLRequest=fJI9b9swEIZ3%2FwqBu0SJ%2FpBDRAZce4iBtDViN0MX40Sda...
```

The CLI opens the default browser to the generated URL where users must authenticate
with the configured SAML identity provider. The URL may be manually entered into the
browser if it cannot be automatically opened.

The CLI login behavior may be customized with the following optional parameters:

- `skip_browser` (default: `false`): If set to `true`, automatic launching of the default
  browser will be skipped. The SAML identity provider URL must be manually entered in a
  browser to complete the authentication flow.
- `abort_on_error` (default: `false`): If set to `true`, the CLI returns an error and
  exits with a non-zero value if it cannot launch the default browser.

</Tab>

<Tab heading="Vault UI">

1. Select "SAML" from the "Method" select box.
1. Enter a role name for the "Role" field or leave blank to use
   the [default role](/vault/api-docs/auth/saml#default_role).
1. Press **Sign in with SAML Provider** and complete the authentication with the
   configured SAML identity provider.

</Tab>

</Tabs>

## Configuration

Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.

1. Enable the SAML authentication method with the `auth enable` CLI command:

   ```shell-session
   $ vault auth enable saml
   ```

1. Use the `/config` endpoint to save the configuration of your SAML identity provider and
   set the default role. You can configure the trust relationship with the SAML Identity
   Provider by either providing a URL for its Metadata document:

   ```shell-session
   $ vault write auth/saml/config \
      default_role="admin" \
      idp_metadata_url="https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata" \
      entity_id="https://my.vault/v1/auth/saml" \
      acs_urls="https://my.vault/v1/auth/saml/callback"
   ```

   or by setting the configuration Metadata manually:

   ```shell-session
   $ vault write auth/saml/config \
      default_role="admin" \
      idp_sso_url="https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml" \
      idp_entity_id="https://www.okta.com/abc123eb9xnIfzlaf697" \
      idp_cert="@path/to/cert.pem" \
      entity_id="https://my.vault/v1/auth/saml" \
      acs_urls="https://my.vault/v1/auth/saml/callback"
   ```

1. Create a named role:

   ```shell-session
   $ vault write auth/saml/role/admin \
       bound_subjects="*@hashicorp.com" \
       bound_subjects_type="glob" \
       token_policies="writer" \
       bound_attributes=group="admin" \
       ttl="1h"
   ```

   This role authorizes users that have a subject with an `@hashicorp.com` suffix and
   are in the `admin` group to authenticate. It also gives the resulting Vault token a
   time-to-live of 1 hour and the `writer` policy.

Refer to the SAML [API documentation](/vault/api-docs/auth/saml) for a
complete list of configuration options.

### Assertion consumer service URLs

The [`acs_urls`](/vault/api-docs/auth/saml#acs_urls) configuration parameter determines
where the SAML response will be sent after users authenticate with the configured SAML
identity provider in their browser.

The values provided to Vault must:

- Match or be a subset of the configured values for the SAML application within the
  configured identity provider.
- Be directed to the auth method's [assertion consumer service
  callback](/vault/api-docs/auth/saml#assertion-consumer-service-callback) API.

<Note>
  It is highly recommended and enforced by some identity providers to TLS-protect the
  assertion consumer service URLs. A warning will be returned from Vault if any of the
  configured assertion consumer service URLs are not protected by TLS.
</Note>

#### Configuration for replication

To support a single auth method mount being used across Vault [replication](/vault/docs/enterprise/replication)
clusters, `acs_urls` supports configuration of multiple values. For example, to support
SAML authentication on a primary and secondary Vault cluster, the following `acs_urls`
configuration could be given:

   ```shell-session
   $ vault write auth/saml/config \
      acs_urls="https://primary.vault/v1/auth/saml/callback,https://secondary.vault/v1/auth/saml/callback"
   ```

The Vault UI and CLI will automatically request the proper assertion consumer service URL
for the cluster they're configured to communicate with. This means that the entirety of the
authentication flow will stay within the targeted cluster.

#### Configuration for namespaces

The SAML auth method can be used within Vault [namespaces](/vault/docs/enterprise/namespaces).
The assertion consumer service URLs configured in both Vault and the identity provider must
include the namespace path segment.

The following table provides assertion consumer service URLs given different namespace paths:

| Namespace path  | Assertion consumer service URL                        |
|-----------------|-------------------------------------------------------|
| `admin/`        | `https://my.vault/v1/admin/auth/saml/callback`        |
| `org/security/` | `https://my.vault/v1/org/security/auth/saml/callback` |

### Bound attributes

Once the user has been authenticated the authorization flow will validate
that both the [`bound_subjects`](/vault/api-docs/auth/saml#bound_subjects) and
[`bound_attributes`](/vault/api-docs/auth/saml#bound_attributes) match expected
values configured for the role. This can be used to restrict access to Vault for
a subset of users in the SAML identity provider.

For example, a role with `bound_subjects=*@hashicorp.com` and
`bound_attributes=groups=support,engineering` will only authorize users whose subject has
an `@hashicorp.com` suffix and that are in either the `support` or `engineering` group.

Whether it should be an exact match or interpret `*` as a wildcard can be
controlled by the [`bound_subjects_type`](/vault/api-docs/auth/saml#bound_subjects_type) and
[`bound_attributes_type`](/vault/api-docs/auth/saml#bound_attributes_type) parameters.

### Bound attributes for the Microsoft identity platform

The bound attributes for the Microsoft identity platform requires
`http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` as the
attribute name along with your group membership values. For example, a role with
`bound_attributes=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups="GROUP1_OBJECT_ID,GROUP2_OBJECT_ID"`
will only authorize users that are in either the `GROUP1_OBJECT_ID` or
`GROUP2_OBJECT_ID` group.

You can read more at the Microsoft identity platform's
[SAML token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/reference-saml-tokens).

## API

The SAML authentication plugin has a full HTTP API. Refer to the
[SAML API documentation](/vault/api-docs/auth/saml) for more details

layout  docs page title  Set up SAML authN description       Use SAML authentication with Vault to authenticate Vault users with public   keys or certificates and a SAML identity provider         Set up SAML authentication   include  alerts enterprise and hcp mdx   The  saml  auth method allows users to authentication with Vault using their identity within a  SAML V2 0  https   saml xml org saml specifications  identity provider  Authentication is suited for human users by requiring interaction with a web browser      Authentication   Tabs    Tab heading  Vault CLI    The CLI login defaults to the   saml  path  If this auth method was enabled at a different path  specify   path  my path  in the CLI      shell session   vault login  method saml role admin  Complete the login via your SAML provider  Launching browser to       https   company okta com app vault abc123eb9xnIfzlaf697 sso saml SAMLRequest fJI9b9swEIZ3 2FwqBu0SJ 2FpBDRAZce4iBtDViN0MX40Sda         The CLI opens the default browser to the generated URL where users must authenticate with the configured SAML identity provider  The URL may be manually entered into the browser if it cannot be automatically opened   The CLI login behavior may be customized with the following optional parameters      skip browser   default   false    If set to  true   automatic launching of the default   browser will be skipped  The SAML identity provider URL must be manually entered in a   browser to complete the authentication flow     abort on error   default   false    If set to  true   the CLI returns an error and   exits with a non zero value if it cannot launch the default browser     Tab    Tab heading  Vault UI    1  Select  SAML  from the  Method  select box  1  Enter a role name for the  Role  field or leave blank to use    the  default role   vault api docs auth saml default role   1  Press   Sign in with SAML Provider   and complete the authentication with the    configured SAML identity provider     Tab     Tabs      Configuration  Auth methods must be configured in advance before users or machines can authenticate  These steps are usually completed by an operator or configuration management tool   1  Enable the SAML authentication method with the  auth enable  CLI command         shell session      vault auth enable saml         1  Use the   config  endpoint to save the configuration of your SAML identity provider and    set the default role  You can configure the trust relationship with the SAML Identity    Provider by either providing a URL for its Metadata document         shell session      vault write auth saml config         default role  admin          idp metadata url  https   company okta com app abc123eb9xnIfzlaf697 sso saml metadata          entity id  https   my vault v1 auth saml          acs urls  https   my vault v1 auth saml callback             or by setting the configuration Metadata manually         shell session      vault write auth saml config         default role  admin          idp sso url  https   company okta com app abc123eb9xnIfzlaf697 sso saml          idp entity id  https   www okta com abc123eb9xnIfzlaf697          idp cert   path to cert pem          entity id  https   my vault v1 auth saml          acs urls  https   my vault v1 auth saml callback          1  Create a named role         shell session      vault write auth saml role admin          bound subjects    hashicorp com           bound subjects type  glob           token policies  writer           bound attributes group  admin           ttl  1h             This role authorizes users that have a subject with an   hashicorp com  suffix and    are in the  admin  group to authenticate  It also gives the resulting Vault token a    time to live of 1 hour and the  writer  policy   Refer to the SAML  API documentation   vault api docs auth saml  for a complete list of configuration options       Assertion consumer service URLs  The   acs urls    vault api docs auth saml acs urls  configuration parameter determines where the SAML response will be sent after users authenticate with the configured SAML identity provider in their browser   The values provided to Vault must     Match or be a subset of the configured values for the SAML application within the   configured identity provider    Be directed to the auth method s  assertion consumer service   callback   vault api docs auth saml assertion consumer service callback  API    Note    It is highly recommended and enforced by some identity providers to TLS protect the   assertion consumer service URLs  A warning will be returned from Vault if any of the   configured assertion consumer service URLs are not protected by TLS    Note        Configuration for replication  To support a single auth method mount being used across Vault  replication   vault docs enterprise replication  clusters   acs urls  supports configuration of multiple values  For example  to support SAML authentication on a primary and secondary Vault cluster  the following  acs urls  configuration could be given         shell session      vault write auth saml config         acs urls  https   primary vault v1 auth saml callback https   secondary vault v1 auth saml callback          The Vault UI and CLI will automatically request the proper assertion consumer service URL for the cluster they re configured to communicate with  This means that the entirety of the authentication flow will stay within the targeted cluster        Configuration for namespaces  The SAML auth method can be used within Vault  namespaces   vault docs enterprise namespaces   The assertion consumer service URLs configured in both Vault and the identity provider must include the namespace path segment   The following table provides assertion consumer service URLs given different namespace paths     Namespace path    Assertion consumer service URL                                                                                admin             https   my vault v1 admin auth saml callback              org security      https   my vault v1 org security auth saml callback         Bound attributes  Once the user has been authenticated the authorization flow will validate that both the   bound subjects    vault api docs auth saml bound subjects  and   bound attributes    vault api docs auth saml bound attributes  match expected values configured for the role  This can be used to restrict access to Vault for a subset of users in the SAML identity provider   For example  a role with  bound subjects   hashicorp com  and  bound attributes groups support engineering  will only authorize users whose subject has an   hashicorp com  suffix and that are in either the  support  or  engineering  group   Whether it should be an exact match or interpret     as a wildcard can be controlled by the   bound subjects type    vault api docs auth saml bound subjects type  and   bound attributes type    vault api docs auth saml bound attributes type  parameters       Bound attributes for the Microsoft identity platform  The bound attributes for the Microsoft identity platform requires  http   schemas microsoft com ws 2008 06 identity claims groups  as the attribute name along with your group membership values  For example  a role with  bound attributes http   schemas microsoft com ws 2008 06 identity claims groups  GROUP1 OBJECT ID GROUP2 OBJECT ID   will only authorize users that are in either the  GROUP1 OBJECT ID  or  GROUP2 OBJECT ID  group   You can read more at the Microsoft identity platform s  SAML token claims reference  https   learn microsoft com en us entra identity platform reference saml tokens       API  The SAML authentication plugin has a full HTTP API  Refer to the  SAML API documentation   vault api docs auth saml  for more details


vault page title Link Active Directory SAML groups to Vault Federation Services AD FS as a SAML provider Connect Vault policies to Active Directory groups with Active Directory layout docs Link Active Directory SAML groups to Vault

Answer:
---
layout: docs
page_title: Link Active Directory SAML groups to Vault
description: >-
  Connect Vault policies to Active Directory groups with Active Directory
  Federation Services (AD FS) as a SAML provider.
---

# Link Active Directory SAML groups to Vault

@include 'alerts/enterprise-and-hcp.mdx'

Configure your Vault instance to link your Active Directory groups to Vault
policies with SAML.

## 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 configured for AD FS](/vault/docs/auth/saml/adfs)**.
- **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`](/vault/docs/commands/token/create) with the Vault CLI.

## Step 1: Enable a `kv` plugin instance for AD clients

<Tabs>

<Tab heading="Vault CLI" group="cli">

Enable an instance of the KV secret engine for AD FS under a custom path:

```shell-session
$ vault secrets enable -path=<ADFS_KV_PLUGIN_PATH> kv-v2
```

For example:

<CodeBlockConfig hideClipboard>

```shell-session
$ vault secrets enable -path=adfs-kv kv-v2
```

</CodeBlockConfig>

</Tab>

<Tab heading="Vault GUI" group="gui">

@include 'gui-instructions/enable-secrets-plugin.mdx'

- Enable the KV plugin:

    1. Select the **KV** token.
    1. Set a mount path that reflects the plugin purpose. For example: `dfs-kv`.
    1. Click **Enable engine**.

</Tab>

</Tabs>

## Step 2: Create a read-only policy for the `kv` plugin

<Tabs>

<Tab heading="Vault CLI" group="cli">

Use `vault write` to create a read-only policy for AD FS clients that use the
new KV plugin:

```shell-session
$ vault policy write <RO_ADFS_POLICY_NAME> - << EOF
# Read and list policy for the AD FS KV mount
path "<ADFS_KV_PLUGIN_PATH>/*" {
  capabilities = ["read", "list"]
}
EOF
```

For example:

<CodeBlockConfig hideClipboard>

```shell-session
$ vault policy write ro-saml-adfs - << EOF
# Read and list policy for the AD FS KV mount
path "adfs-kv/*" {
  capabilities = ["read", "list"]
}
EOF
```

</CodeBlockConfig>

</Tab>

<Tab heading="Vault GUI" group="gui">

@include 'gui-instructions/create-acl-policy.mdx'

- Set the policy details and click **Create policy**:

    - **Name**: "ro-saml-adfs"
    - **Policy**:
    ```hcl
    # Read and list policy for the AD FS KV mount
    path "<ADFS_KV_PLUGIN_PATH>/*" {
      capabilities = ["read", "list"]
    }
    ```

</Tab>

</Tabs>

## Step 3: Create and link a Vault group to AD

<Tabs>

<Tab heading="Vault CLI" group="cli">

1. Create an external group in Vault and save the group ID to a file named
   `group_id.txt`:

   ```shell-session
   $ vault write                            \
     -format=json                           \
     identity/group name="SamlVaultReader"  \
     policies="ro-adfs-test"                \
     type="external" | jq -r ".data.id" > group_id.txt
   ```

1. Retrieve the mount accessor for the AD FS authentication method and save it
   to a file named `accessor_adfs.txt`:

   ```shell-session
   $ vault auth list -format=json |               \
     jq -r '.["<SAML_PLUGIN_PATH>/"].accessor' >  \
     accessor_adfs.txt
   ```

1. Create a group alias:

   ```shell-session
   $ vault write identity/group-alias         \
     name="<YOUR_EXISTING_AD_GROUP>"          \
     mount_accessor=$(cat accessor_adfs.txt)  \
     canonical_id="$(cat group_id.txt)"
   ```

</Tab>

<Tab heading="Vault GUI" group="gui">

@include 'gui-instructions/create-group.mdx'

- Follow the prompts to create an external group with the following
  information:
     - Name: your new Vault group name
     - Type: `external`
     - Policies: the read-only AD FS policy you created. For example,
       `ro-adfs-test`.

- Click **Add alias** and follow the prompts to map the Vault group name to an
  existing group in Active Directory:
   - Name: the name of an existing AD group (**must match exactly**).
   - Auth Backend: `<SAML_PLUGIN_PATH>/ (saml)`

</Tab>

</Tabs>

## Step 4: Verify the link to Active Directory

1. Use the Vault CLI to login as an Active Directory user who is a member of
   the linked Active Directory group:

   ```shell-session
   $ vault login -method saml -path <SAML_PLUGIN_PATH>
   ```

1. Read your test value from the KV plugin:

   ```shell-session
   $ vault kv get adfs-kv/test
   ```

layout  docs page title  Link Active Directory SAML groups to Vault description       Connect Vault policies to Active Directory groups with Active Directory   Federation Services  AD FS  as a SAML provider         Link Active Directory SAML groups to Vault   include  alerts enterprise and hcp mdx   Configure your Vault instance to link your Active Directory groups to Vault policies with SAML        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 configured for AD FS   vault docs auth saml adfs         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    vault docs commands token create  with the Vault CLI        Step 1  Enable a  kv  plugin instance for AD clients   Tabs    Tab heading  Vault CLI  group  cli    Enable an instance of the KV secret engine for AD FS under a custom path      shell session   vault secrets enable  path  ADFS KV PLUGIN PATH  kv v2      For example    CodeBlockConfig hideClipboard      shell session   vault secrets enable  path adfs kv kv v2        CodeBlockConfig     Tab    Tab heading  Vault GUI  group  gui     include  gui instructions enable secrets plugin mdx     Enable the KV plugin       1  Select the   KV   token      1  Set a mount path that reflects the plugin purpose  For example   dfs kv       1  Click   Enable engine       Tab     Tabs       Step 2  Create a read only policy for the  kv  plugin   Tabs    Tab heading  Vault CLI  group  cli    Use  vault write  to create a read only policy for AD FS clients that use the new KV plugin      shell session   vault policy write  RO ADFS POLICY NAME       EOF   Read and list policy for the AD FS KV mount path   ADFS KV PLUGIN PATH         capabilities     read    list     EOF      For example    CodeBlockConfig hideClipboard      shell session   vault policy write ro saml adfs      EOF   Read and list policy for the AD FS KV mount path  adfs kv        capabilities     read    list     EOF        CodeBlockConfig     Tab    Tab heading  Vault GUI  group  gui     include  gui instructions create acl policy mdx     Set the policy details and click   Create policy             Name     ro saml adfs          Policy           hcl       Read and list policy for the AD FS KV mount     path   ADFS KV PLUGIN PATH             capabilities     read    list                    Tab     Tabs        Step 3  Create and link a Vault group to AD   Tabs    Tab heading  Vault CLI  group  cli    1  Create an external group in Vault and save the group ID to a file named     group id txt          shell session      vault write                                    format json                                  identity group name  SamlVaultReader          policies  ro adfs test                        type  external    jq  r   data id    group id txt         1  Retrieve the mount accessor for the AD FS authentication method and save it    to a file named  accessor adfs txt          shell session      vault auth list  format json                        jq  r      SAML PLUGIN PATH     accessor            accessor adfs txt         1  Create a group alias         shell session      vault write identity group alias                name   YOUR EXISTING AD GROUP                   mount accessor   cat accessor adfs txt          canonical id    cat group id txt              Tab    Tab heading  Vault GUI  group  gui     include  gui instructions create group mdx     Follow the prompts to create an external group with the following   information         Name  your new Vault group name        Type   external         Policies  the read only AD FS policy you created  For example          ro adfs test      Click   Add alias   and follow the prompts to map the Vault group name to an   existing group in Active Directory       Name  the name of an existing AD group    must match exactly          Auth Backend    SAML PLUGIN PATH    saml      Tab     Tabs       Step 4  Verify the link to Active Directory  1  Use the Vault CLI to login as an Active Directory user who is a member of    the linked Active Directory group         shell session      vault login  method saml  path  SAML PLUGIN PATH          1  Read your test value from the KV plugin         shell session      vault kv get adfs kv test


vault policies when using Active Directory Federation Services ADFS as an SAML provider page title Troubleshoot ADFS and SAML automatic group mapping fails layout docs Fix connection problems in Vault due to a bad mapping between groups and Automatic group mapping fails

Answer:
---
layout: docs
page_title: "Troubleshoot ADFS and SAML: automatic group mapping fails"
description: >-
  Fix connection problems in Vault due to a bad mapping between groups and
  policies when using Active Directory Federation Services (ADFS) as an SAML
  provider.
---

# Automatic group mapping fails

Troubleshoot problems where the debugging data suggests a bad or nonexistent
mapping between your Vault role and AD FS the Claim Issuance Policy.

## Example debugging data

<CodeBlockConfig hideClipboard highlight="14,16,21">

```json
[DEBUG] auth.saml.auth_saml_1d2227e7: validating user context for role: api=callback role_name=default-saml
role="{
  "token_bound_cidrs":null,
  "token_explicit_max_ttl":0,
  "token_max_ttl":0,
  "token_no_default_policy":false,
  "token_num_uses":0,
  "token_period":0,
  "token_policies":["default"],
  "token_type":0,
  "token_ttl":0,
  "BoundSubjects":["*@example.com","*@ext.example.com"],
  "BoundSubjectsType":"glob",
  "BoundAttributes":{"http://schemas.xmlsoap.org/claims/Group":["VaultAdmin","VaultUser"]},
  "BoundAttributesType":"string",
  "GroupsAttribute":"groups"
  }"
user context="{
  "attributes":
  {
    "http://schemas.xmlsoap.org/claims/Group":["Domain Users","VaultAdmin"],
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress":["rs@example.com"]
  },
  "subject":"rs@example.com"
}"
```

</CodeBlockConfig>

## Analysis

Use `vault read` to review the current role configuration:

<CodeBlockConfig hideClipboard highlight="5,9">

```shell-session
$ vault read auth/<SAML_PLUGIN_PATH>/role/<ADFS_ROLE>

Key                        Value
---                        -----
bound_attributes           map[http://schemas.xmlsoap.org/claims/Group:[VaultAdmin VaultUser]]
bound_attributes_type      string
bound_subjects             [*@example.com *@ext.example.com]
bound_subjects_type        glob
groups_attribute           groups
token_bound_cidrs          []
token_explicit_max_ttl     0s
token_max_ttl              0s
token_no_default_policy    false
token_num_uses             0
token_period               0s
token_policies             [default]
token_ttl                  0s
token_type                 default
```

</CodeBlockConfig>

The Vault role uses `groups` for the group attribute, so Vault expects user
context in the SAML response to include a `groups` attribute with the form:

<CodeBlockConfig hideClipboard>

```text
user context="{
  "attributes":
  {
    "groups":[<LIST_OF_BOUND_GROUPS>]",
    ...
  }
}"
```
</CodeBlockConfig>

But the SAML response indicates the Claim Issuance Policy uses `Group` for the
group attribute, so the user context uses `Group` to key the bound groups:

<CodeBlockConfig hideClipboard>

```text
user context="{
  "attributes":
  {
    "http://schemas.xmlsoap.org/claims/Group":["Domain Users","VaultAdmin"],
    ...
  },
  "subject":"rs@example.com"
}"
```

</CodeBlockConfig>

## Solution

<Tabs>

<Tab heading="Option 1: Use 'Group' in the Vault role">

The first option to resolve the problem is update `group_attribute` for the
Vault role to use `Group`:

```shell-session
$ vault write auth/<SAML_PLUGIN_PATH>/role/<ADFS_ROLE> \
    groups_attribute=http://schemas.xmlsoap.org/claims/Group
```

For example:

<CodeBlockConfig hideClipboard>

```shell-session
$ vault write auth/saml/role/adfs-default \
    groups_attribute=http://schemas.xmlsoap.org/claims/Group
```

</CodeBlockConfig>

</Tab>

<Tab heading="Option 2: Use 'groups' for AD FS">

The second option to resolve the problem is to update your AD FS configuration
to use `groups` and confirm the bound attributes in Vault match the expected
groups:

1. Update your AD FS the Claim Issuance Policy to use `groups` for unqualified
   names:

    | LDAP attribute                     | Outgoing claim type
    |------------------------------------|--------------------
    | `Token-Groups - Unqualified Names` | `groups`

1. Verify the bound attribute for your Vault role match the groups listed in the
   SAML response:

    ```shell-session
    $ vault write auth/<SAML_PLUGIN_PATH>/role/<ADFS_ROLE> \
        bound_attributes=groups="<AD_GROUP_LIST>"
    ```

    For example:

    <CodeBlockConfig hideClipboard>

    ```shell-session
    $ vault write auth/saml/role/default-adfs \
        bound_attributes=groups="VaultAdmin,VaultUser"
    ```

    </CodeBlockConfig>

</Tab>
</Tabs>

## Additional resources

- [SAML auth method Documentation](/vault/docs/auth/saml)
- [SAML API Documentation](/vault/api-docs/auth/saml)
- [Set up an AD FS lab environment](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/set-up-an-ad-fs-lab-environment)

layout  docs page title   Troubleshoot ADFS and SAML  automatic group mapping fails  description       Fix connection problems in Vault due to a bad mapping between groups and   policies when using Active Directory Federation Services  ADFS  as an SAML   provider         Automatic group mapping fails  Troubleshoot problems where the debugging data suggests a bad or nonexistent mapping between your Vault role and AD FS the Claim Issuance Policy        Example debugging data   CodeBlockConfig hideClipboard highlight  14 16 21       json  DEBUG  auth saml auth saml 1d2227e7  validating user context for role  api callback role name default saml role       token bound cidrs  null     token explicit max ttl  0     token max ttl  0     token no default policy  false     token num uses  0     token period  0     token policies    default       token type  0     token ttl  0     BoundSubjects      example com     ext example com       BoundSubjectsType   glob      BoundAttributes    http   schemas xmlsoap org claims Group    VaultAdmin   VaultUser        BoundAttributesType   string      GroupsAttribute   groups       user context       attributes            http   schemas xmlsoap org claims Group    Domain Users   VaultAdmin         http   schemas xmlsoap org ws 2005 05 identity claims emailaddress    rs example com           subject   rs example com            CodeBlockConfig        Analysis  Use  vault read  to review the current role configuration    CodeBlockConfig hideClipboard highlight  5 9       shell session   vault read auth  SAML PLUGIN PATH  role  ADFS ROLE   Key                        Value                                  bound attributes           map http   schemas xmlsoap org claims Group  VaultAdmin VaultUser   bound attributes type      string bound subjects                example com   ext example com  bound subjects type        glob groups attribute           groups token bound cidrs             token explicit max ttl     0s token max ttl              0s token no default policy    false token num uses             0 token period               0s token policies              default  token ttl                  0s token type                 default        CodeBlockConfig   The Vault role uses  groups  for the group attribute  so Vault expects user context in the SAML response to include a  groups  attribute with the form    CodeBlockConfig hideClipboard      text user context       attributes            groups    LIST OF BOUND GROUPS                          CodeBlockConfig   But the SAML response indicates the Claim Issuance Policy uses  Group  for the group attribute  so the user context uses  Group  to key the bound groups     CodeBlockConfig hideClipboard      text user context       attributes            http   schemas xmlsoap org claims Group    Domain Users   VaultAdmin                    subject   rs example com            CodeBlockConfig        Solution   Tabs    Tab heading  Option 1  Use  Group  in the Vault role    The first option to resolve the problem is update  group attribute  for the Vault role to use  Group       shell session   vault write auth  SAML PLUGIN PATH  role  ADFS ROLE        groups attribute http   schemas xmlsoap org claims Group      For example    CodeBlockConfig hideClipboard      shell session   vault write auth saml role adfs default       groups attribute http   schemas xmlsoap org claims Group        CodeBlockConfig     Tab    Tab heading  Option 2  Use  groups  for AD FS    The second option to resolve the problem is to update your AD FS configuration to use  groups  and confirm the bound attributes in Vault match the expected groups   1  Update your AD FS the Claim Issuance Policy to use  groups  for unqualified    names         LDAP attribute                       Outgoing claim type                                                                       Token Groups   Unqualified Names     groups   1  Verify the bound attribute for your Vault role match the groups listed in the    SAML response          shell session       vault write auth  SAML PLUGIN PATH  role  ADFS ROLE            bound attributes groups   AD GROUP LIST                For example        CodeBlockConfig hideClipboard          shell session       vault write auth saml role default adfs           bound attributes groups  VaultAdmin VaultUser                 CodeBlockConfig     Tab    Tabs        Additional resources     SAML auth method Documentation   vault docs auth saml     SAML API Documentation   vault api docs auth saml     Set up an AD FS lab environment  https   learn microsoft com en us windows server identity ad fs operations set up an ad fs lab environment


vault Learn about Vault s plugin architecture page title External Plugin Architecture External plugin architecture layout docs executes and communicates with over RPC This means the plugin process does not Vault s external plugins are completely separate standalone applications that Vault

Answer:
---
layout: docs
page_title: External Plugin Architecture
description: Learn about Vault's plugin architecture.
---

# External plugin architecture

Vault's external plugins are completely separate, standalone applications that Vault
executes and communicates with over RPC. This means the plugin process does not
share the same memory space as Vault and therefore can only access the
interfaces and arguments given to it. This also means a crash in a plugin cannot
crash the entirety of Vault.

It is possible to enable a custom plugin with a name that's identical to a
built-in plugin. In such a situation, Vault will always choose the custom plugin
when enabling it.

-> **NOTE:** See the [Vault Integrations](/vault/integrations) page to find a
curated collection of official, partner, and community Vault plugins.

## External plugin lifecycle

Vault external plugins are long-running processes that remain running once they are
spawned by Vault, the parent process. Plugin processes can be started by Vault's
active node and performance standby nodes. Additionally, there are cases where
plugin processes may be terminated by Vault. These cases include, but are not
limited to:

- Vault active node step-down
- Vault barrier seal
- Vault graceful shutdown
- Disabling a Secrets Engine or Auth method that uses external plugins
- Database configured connection deletion
- Database configured connection update
- Database configured connection reset request
- Database root credentials rotation
- WAL Rollback from a previously failed root credentials rotation operation

The lifecycle of plugin processes are managed automatically by Vault.
Termination of these processes are typical in certain scenarios, such as the
ones listed above. Vault will start plugin processes when they are enabled. A
plugin process may be started or terminated through other internal processes
within Vault as well. Since Vault manages and tracks the lifecycle of its
plugins, these processes should not be terminated by anything other than Vault.
If a plugin process is shutdown out-of-band, the plugin process will be lazily
loaded when a request that requires the plugin is received by Vault.

### External plugin scaling characteristics

External plugins can leverage [Performance Standbys](/vault/docs/enterprise/performance-standby)
without any explicit action by a plugin author. The default behavior of Vault
Enterprise is to attempt to handle all requests, including requests to plugins,
on performance standbys. If the plugin request makes any attempt to modify
storage, the request will receive a readonly error, and the request routing
code will then forward the full original request transparently to the active
node. In other words, plugins can scale horizontally on Vault Enterprise
without any effort on the plugin author's part.

## Plugin communication

Vault communicates with external plugins over RPC. To secure this
communication, Vault creates a mutually authenticated TLS connection with the
plugin's RPC server. Plugins make use of the AutoMTLS feature of
[go-plugin](https://www.github.com/hashicorp/go-plugin) which will
automatically negotiate mutual TLS for transport authentication.

The [`api_addr`](/vault/docs/configuration#api_addr) must be set in order for the
plugin process to establish communication with the Vault server during mount
time. If the storage backend has HA enabled and supports automatic host address
detection (e.g. Consul), Vault will automatically attempt to determine the
`api_addr` as well.

~> Note: Prior to Vault version 1.9.2, reading the original connection's TLS
connection state is not supported in plugins.

## Plugin registration

An important consideration of Vault's plugin system is to ensure the plugin
invoked by Vault is authentic and maintains integrity. There are two components
that a Vault operator needs to configure before external plugins can be run- the
plugin directory and the plugin catalog entry.

### Plugin directory

The plugin directory is a configuration option of Vault and can be specified in
the [configuration file](/vault/docs/configuration).
This setting specifies a directory in which all plugin binaries must live;
_this value cannot be a symbolic link_. A plugin
cannot be added to Vault unless it exists in the plugin directory. There is no
default for this configuration option, and if it is not set, plugins cannot be
added to Vault.

@include 'plugin-file-permissions-check.mdx'

### Plugin catalog

The plugin catalog is Vault's list of approved plugins. The catalog is stored in
Vault's barrier and can only be updated by a Vault user with sudo permissions.
Upon adding a new plugin, the plugin name, SHA256 sum of the executable, and the
command that should be used to run the plugin must be provided. The catalog will
ensure the executable referenced in the command exists in the plugin
directory. When added to the catalog, the plugin is not automatically executed,
but becomes visible to backends and can be executed by them. For more
information on the plugin catalog please see the [Plugin Catalog API
docs](/vault/api-docs/system/plugins-catalog).

An example of plugin registration in current versions of Vault:

```shell-session
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    secret \                  # type
    myplugin-database-plugin

Success! Registered plugin: myplugin-database-plugin
```

Vault versions prior to v0.10.4 lacked the `vault plugin` operator and the
registration step for them is:

```shell-session
$ vault write sys/plugins/catalog/database/myplugin-database-plugin \
     sha256=<SHA256 Hex value of the plugin binary> \
     command="myplugin"

Success! Data written to: sys/plugins/catalog/database/myplugin-database-plugin
```

### Plugin execution

When a backend wants to run a plugin, it first looks up the plugin, by name, in
the catalog. It then checks the executable's SHA256 sum against the one
configured in the plugin catalog. Finally Vault runs the command configured in
the catalog, sending along the JWT formatted response wrapping token and mlock
settings. Like Vault, plugins support [the use of mlock when available](/vault/docs/configuration#disable_mlock).

~> Note: If Vault is configured with `mlock` enabled, then the Vault executable
and each plugin executable in your [plugins directory](/vault/docs/plugins/plugin-architecture#plugin-directory)
must be given the ability to use the `mlock` syscall.

### Plugin upgrades

External plugins may be updated by registering and reloading them. More details
on the upgrade procedure can be found in
[Upgrading Vault Plugins](/vault/docs/upgrading/plugins).

## Plugin multiplexing

To avoid spawning multiple plugin processes for mounts of the same type,
plugins can implement plugin multiplexing. This allows a single
plugin process to be used for multiple mounts of a given type. This single
process will be multiplexed across all Vault namespaces for mounts of this
type. Multiplexing a plugin does not affect the current behavior of existing
plugins.

To enable multiplexing, the plugin must be compiled with the `ServeMultiplex`
function call from Vault's respective `plugin` or `dbplugin` SDK packages. At
this time, there is no opt-out capability for plugins that implement
multiplexing. To use a non-multiplexed plugin, run an older version of the
plugin, i.e., the plugin calls the `Serve` function.

More resources on implementing plugin multiplexing:
* [Database secrets engines](/vault/docs/secrets/databases/custom#serving-a-plugin-with-multiplexing)
* [Secrets engines and auth methods](/vault/docs/plugins/plugin-development)

## Troubleshooting

### Unrecognized remote plugin message

If the following error is encountered when enabling a plugin secret engine or
auth method:

<CodeBlockConfig hideClipboard>

```sh
Unrecognized remote plugin message:

This usually means that the plugin is either invalid or simply
needs to be recompiled to support the latest protocol.
```

</CodeBlockConfig>

Verify whether the Vault process has `mlock` enabled, and if so, run the
following command against the plugin binary:

```shell-session
$ sudo setcap cap_ipc_lock=+ep <plugin-binary>
```

layout  docs page title  External Plugin Architecture description  Learn about Vault s plugin architecture         External plugin architecture  Vault s external plugins are completely separate  standalone applications that Vault executes and communicates with over RPC  This means the plugin process does not share the same memory space as Vault and therefore can only access the interfaces and arguments given to it  This also means a crash in a plugin cannot crash the entirety of Vault   It is possible to enable a custom plugin with a name that s identical to a built in plugin  In such a situation  Vault will always choose the custom plugin when enabling it        NOTE    See the  Vault Integrations   vault integrations  page to find a curated collection of official  partner  and community Vault plugins      External plugin lifecycle  Vault external plugins are long running processes that remain running once they are spawned by Vault  the parent process  Plugin processes can be started by Vault s active node and performance standby nodes  Additionally  there are cases where plugin processes may be terminated by Vault  These cases include  but are not limited to     Vault active node step down   Vault barrier seal   Vault graceful shutdown   Disabling a Secrets Engine or Auth method that uses external plugins   Database configured connection deletion   Database configured connection update   Database configured connection reset request   Database root credentials rotation   WAL Rollback from a previously failed root credentials rotation operation  The lifecycle of plugin processes are managed automatically by Vault  Termination of these processes are typical in certain scenarios  such as the ones listed above  Vault will start plugin processes when they are enabled  A plugin process may be started or terminated through other internal processes within Vault as well  Since Vault manages and tracks the lifecycle of its plugins  these processes should not be terminated by anything other than Vault  If a plugin process is shutdown out of band  the plugin process will be lazily loaded when a request that requires the plugin is received by Vault       External plugin scaling characteristics  External plugins can leverage  Performance Standbys   vault docs enterprise performance standby  without any explicit action by a plugin author  The default behavior of Vault Enterprise is to attempt to handle all requests  including requests to plugins  on performance standbys  If the plugin request makes any attempt to modify storage  the request will receive a readonly error  and the request routing code will then forward the full original request transparently to the active node  In other words  plugins can scale horizontally on Vault Enterprise without any effort on the plugin author s part      Plugin communication  Vault communicates with external plugins over RPC  To secure this communication  Vault creates a mutually authenticated TLS connection with the plugin s RPC server  Plugins make use of the AutoMTLS feature of  go plugin  https   www github com hashicorp go plugin  which will automatically negotiate mutual TLS for transport authentication   The   api addr    vault docs configuration api addr  must be set in order for the plugin process to establish communication with the Vault server during mount time  If the storage backend has HA enabled and supports automatic host address detection  e g  Consul   Vault will automatically attempt to determine the  api addr  as well      Note  Prior to Vault version 1 9 2  reading the original connection s TLS connection state is not supported in plugins      Plugin registration  An important consideration of Vault s plugin system is to ensure the plugin invoked by Vault is authentic and maintains integrity  There are two components that a Vault operator needs to configure before external plugins can be run  the plugin directory and the plugin catalog entry       Plugin directory  The plugin directory is a configuration option of Vault and can be specified in the  configuration file   vault docs configuration   This setting specifies a directory in which all plugin binaries must live   this value cannot be a symbolic link   A plugin cannot be added to Vault unless it exists in the plugin directory  There is no default for this configuration option  and if it is not set  plugins cannot be added to Vault    include  plugin file permissions check mdx       Plugin catalog  The plugin catalog is Vault s list of approved plugins  The catalog is stored in Vault s barrier and can only be updated by a Vault user with sudo permissions  Upon adding a new plugin  the plugin name  SHA256 sum of the executable  and the command that should be used to run the plugin must be provided  The catalog will ensure the executable referenced in the command exists in the plugin directory  When added to the catalog  the plugin is not automatically executed  but becomes visible to backends and can be executed by them  For more information on the plugin catalog please see the  Plugin Catalog API docs   vault api docs system plugins catalog    An example of plugin registration in current versions of Vault      shell session   vault plugin register  sha256  SHA256 Hex value of the plugin binary        secret                      type     myplugin database plugin  Success  Registered plugin  myplugin database plugin      Vault versions prior to v0 10 4 lacked the  vault plugin  operator and the registration step for them is      shell session   vault write sys plugins catalog database myplugin database plugin        sha256  SHA256 Hex value of the plugin binary         command  myplugin   Success  Data written to  sys plugins catalog database myplugin database plugin          Plugin execution  When a backend wants to run a plugin  it first looks up the plugin  by name  in the catalog  It then checks the executable s SHA256 sum against the one configured in the plugin catalog  Finally Vault runs the command configured in the catalog  sending along the JWT formatted response wrapping token and mlock settings  Like Vault  plugins support  the use of mlock when available   vault docs configuration disable mlock       Note  If Vault is configured with  mlock  enabled  then the Vault executable and each plugin executable in your  plugins directory   vault docs plugins plugin architecture plugin directory  must be given the ability to use the  mlock  syscall       Plugin upgrades  External plugins may be updated by registering and reloading them  More details on the upgrade procedure can be found in  Upgrading Vault Plugins   vault docs upgrading plugins       Plugin multiplexing  To avoid spawning multiple plugin processes for mounts of the same type  plugins can implement plugin multiplexing  This allows a single plugin process to be used for multiple mounts of a given type  This single process will be multiplexed across all Vault namespaces for mounts of this type  Multiplexing a plugin does not affect the current behavior of existing plugins   To enable multiplexing  the plugin must be compiled with the  ServeMultiplex  function call from Vault s respective  plugin  or  dbplugin  SDK packages  At this time  there is no opt out capability for plugins that implement multiplexing  To use a non multiplexed plugin  run an older version of the plugin  i e   the plugin calls the  Serve  function   More resources on implementing plugin multiplexing     Database secrets engines   vault docs secrets databases custom serving a plugin with multiplexing     Secrets engines and auth methods   vault docs plugins plugin development      Troubleshooting      Unrecognized remote plugin message  If the following error is encountered when enabling a plugin secret engine or auth method    CodeBlockConfig hideClipboard      sh Unrecognized remote plugin message   This usually means that the plugin is either invalid or simply needs to be recompiled to support the latest protocol         CodeBlockConfig   Verify whether the Vault process has  mlock  enabled  and if so  run the following command against the plugin binary      shell session   sudo setcap cap ipc lock  ep  plugin binary