A new platform for documentation and tutorials is launching soon.

We are migrating Vault documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»Login MFA

Vault supports Multi-factor Authentication (MFA) for authenticating to an auth method using different authentication types. We use the term Login MFA to distinguish this feature and the Vault Enterprise MFA. Login MFA is built on top of the Identity system of Vault.

»MFA Types

MFA in Vault includes the following login types:

  • Time-based One-time Password (TOTP) - If configured and enabled on a login path, this would require a TOTP passcode along with a Vault token to be presented while invoking the API login request. The passcode will be validated against the TOTP key present in the caller's identify in Vault.

  • Okta - If Okta push is configured and enabled on a login path, then the enrolled device of the user will receive a push notification to either approve or deny access to the API. The Okta username will be derived from the caller identity's alias.

  • Duo - If Duo push is configured and enabled on a login path, then the enrolled device of the user will receive a push notification to either approve or deny access to the API. The Duo username will be derived from the caller identity's alias. Note that Duo could also be configured to use passcodes for authentication.

  • PingID - If PingID push is configured and enabled on a login path, the enrolled device of the user will receive a push notification to either approve or deny access to the API. The PingID username will be derived from the caller identity's alias.

»Login MFA Procedure

NOTE: Vault's built-in Login MFA feature does not protect against brute forcing of TOTP passcodes by default. We recommend that per-client rate limits are applied to the relevant login and/or mfa paths (e.g. /sys/mfa/validate). External MFA methods (Duo, Ping and Okta) may already provide configurable rate limiting. Rate limiting of Login MFA paths are enforced by default in Vault 1.10.1 and above.

Login MFA can be configured to secure further authenticating to an auth method. To enable login MFA, an MFA method needs to be configured. Please see Login MFA API for details on how to configure an MFA method. Once an MFA method is configured, an operator can configure an MFA enforcement using the returned unique MFA method ID. Please see Login MFA Enforcement API for details on how to configure an MFA enforcement config. MFA could be enforced for an entity, a group of entities, a specific auth method accessor, or an auth method type. A login request that matches any MFA enforcement restrictions is subject to further MFA validation, such as a one-time passcode, before being authenticated.

There are two ways to validate a login request that is subject to MFA validation.

»Single-Phase Login

In the Single-phase login, the required MFA information is embedded in a login request using the X-Vault-MFA header. In this case, the MFA validation is done as a part of the login request.

MFA credentials are retrieved from the X-Vault-MFA HTTP header. The format of the header is mfa_method_id[:passcode]. The item in the [] is optional. If there are multiple MFA methods that need to be validated, a user can pass in multiple X-Vault-MFA HTTP headers.

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10:695452" \
    http://127.0.0.1:8200/v1/auth/userpass/login/alice

$ curl \
    --header "X-Vault-Token: ..." \
    --header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10:695452" \
    http://127.0.0.1:8200/v1/auth/userpass/login/alice

If an MFA method does not require a passcode, the login request MFA header only contains the method ID.

 $ curl \
     --header "X-Vault-Token: ..." \
     --header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10" \
     http://127.0.0.1:8200/v1/auth/userpass/login/alice

 $ curl \
     --header "X-Vault-Token: ..." \
     --header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10" \
     http://127.0.0.1:8200/v1/auth/userpass/login/alice

»Two-Phase Login

The more conventional and prevalent MFA method is a two-request mechanism, also referred to as Two-phase Login MFA. In Two-phase login, the X-Vault-MFA header is not provided in the request. In this case, after sending a regular login request, the user receives an auth response in which MFA requirements are included. MFA requirements contain an MFA request ID which identifies the login request that needs validation. In addition, MFA requirements contain MFA constraints that determine which MFA types should be used to validate the request, the corresponding method IDs, and a boolean value showing whether the MFA method uses passcodes or not. MFA constraints form a nested map in MFA Requirement and represent all MFA enforcements that match a login request. While the example below is for the userpass login, note that this can affect the login response on any auth mount protected by MFA validation.

»Sample Two-Phase Login Response

{
  "request_id": "1044c151-13ea-1cf5-f6ed-000c42efd477",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": null,
  "warnings": [
    "A login request was issued that is subject to MFA validation. Please make sure to validate the login by sending another request to mfa/validate endpoint."
  ],
  "auth": {
    "client_token": "",
    "accessor": "",
    "policies": null,
    "token_policies": null,
    "identity_policies": null,
    "metadata": null,
    "orphan": false,
    "entity_id": "",
    "lease_duration": 0,
    "renewable": false,
    "mfa_requirement": {
      "mfa_request_id": "d0c9eec7-6921-8cc0-be62-202b289ef163",
      "mfa_constraints": {
        "enforcementConfigUserpass": {
          "any": [
            {
              "type": "totp",
              "id": "820997b3-110e-c251-7e8b-ff4aa428a6e1",
              "uses_passcode": true
            }
          ]
        }
      }
    }
  }
}

{
  "request_id": "1044c151-13ea-1cf5-f6ed-000c42efd477",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": null,
  "warnings": [
    "A login request was issued that is subject to MFA validation. Please make sure to validate the login by sending another request to mfa/validate endpoint."
  ],
  "auth": {
    "client_token": "",
    "accessor": "",
    "policies": null,
    "token_policies": null,
    "identity_policies": null,
    "metadata": null,
    "orphan": false,
    "entity_id": "",
    "lease_duration": 0,
    "renewable": false,
    "mfa_requirement": {
      "mfa_request_id": "d0c9eec7-6921-8cc0-be62-202b289ef163",
      "mfa_constraints": {
        "enforcementConfigUserpass": {
          "any": [
            {
              "type": "totp",
              "id": "820997b3-110e-c251-7e8b-ff4aa428a6e1",
              "uses_passcode": true
            }
          ]
        }
      }
    }
  }
}

Note that the uses_passcode boolean value is always set to true for TOTP, and must always be set to false for Okta and PingID. For Duo method, the value can be configured as part of the method configuration. Please see Duo API for details on how to configure the boolean value for Duo.

To validate the MFA restricted login request, the user sends a second request to the validate endpoint including the MFA request ID and MFA payload. MFA payload contains a map of methodIDs and their associated credentials. If the configured MFA methods, such as PingID, Okta, and Duo, do not require a passcode, the associated credentials will be a list with one empty string.

»Sample Payload

{
  "mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
  "mfa_payload": {
    "d16fd3c2-50de-0b9b-eed3-0301dadeca10": ["910201"]
  }
}

{
  "mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
  "mfa_payload": {
    "d16fd3c2-50de-0b9b-eed3-0301dadeca10": ["910201"]
  }
}

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/mfa/validate

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/mfa/validate

»Sample CLI Request

A user is also able to use the CLI write command to validate the login request.

$ vault write sys/mfa/validate -format=json @payload.json

$ vault write sys/mfa/validate -format=json @payload.json

»Interactive CLI for Login MFA

Vault supports an interactive way of authenticating to an auth method using CLI only if the login request is subject to a single MFA method validation. In this situation, if the MFA method is configured to use passcodes, after sending a regular login request, the user is prompted to insert the passcode. Upon successful MFA validation, a client token is returned. If the configured MFA methods, such as PingID, Okta, and Duo, do not require a passcode and have out of band mechanisms for verifying the extra factor, the user is notified to check their authenticator application. This alleviates a user from sending the second request separately to validate a login request. To disable the interactive login experience, a user needs to pass in the non-interactive flag to the login request.

$ vault write -non-interactive sys/mfa/validate -format=json @payload.json

$ vault write -non-interactive sys/mfa/validate -format=json @payload.json

To get started with Login MFA, refer to the Login MFA tutorial.

»TOTP Passcode Validation Rate Limit

Rate limiting of Login MFA paths are enforced by default in Vault 1.10.1 and above. By default, Vault allows for 5 consecutive failed TOTP passcode validation. This value can also be configured by adding max_validation_attempts to the TOTP configuration. If the number of consecutive failed TOTP passcode validation exceeds the configured value, the user needs to wait until a fresh TOTP passcode is available.