Login MFA docs (#14317)
* MFA config docs * correcting some issues * feedback * add a note about deleting methods * Login MFA docs * rename and mdx * adding missing docs nav data * some fixes * interactive login request * Apply suggestions from code review Co-authored-by: Josh Black <raskchanky@users.noreply.github.com> * feedback * feedback * Apply suggestions from code review Co-authored-by: Pratyoy Mukhopadhyay <35388175+pmmukh@users.noreply.github.com> * feedback on mount accessor * Apply suggestions from code review Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> Co-authored-by: Pratyoy Mukhopadhyay <35388175+pmmukh@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update login-mfa.mdx Co-authored-by: Josh Black <raskchanky@gmail.com> Co-authored-by: Josh Black <raskchanky@users.noreply.github.com> Co-authored-by: Pratyoy Mukhopadhyay <35388175+pmmukh@users.noreply.github.com> Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
This commit is contained in:
hghaf099
GitHub
parent
8aa18a20a2
commit
0bf9a38b36
|
|
@ -20,6 +20,7 @@ description: >-
|
|||
## Other
|
||||
|
||||
- [Login Enforcement](/api/secret/identity/mfa/login-enforcement)
|
||||
- [MFA Validate](/api/system/mfa/validate)
|
||||
|
||||
While the above endpoints are available in both the open source and Enterprise versions of Vault,
|
||||
they are namespace aware. MFA methods and login enforcements created in one namespace are separate from other
|
||||
|
|
|
|||
|
|
@ -0,0 +1,83 @@
|
|||
---
|
||||
layout: api
|
||||
page_title: /sys/mfa/validate - HTTP API
|
||||
description: >-
|
||||
The '/sys/mfa/validate' endpoint focuses on validating login MFA requests.
|
||||
If validation succeeds, it returns an auth response which includes a client token.
|
||||
---
|
||||
|
||||
## Validate Login MFA Request
|
||||
|
||||
This endpoint validates a login request which is subject to MFA validation.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------ |
|
||||
| `POST` | `/sys/mfa/validate` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `mfa_request_id` `(string: <required>)` – A unique identification of an MFA restricted login request.
|
||||
This can be found in the MFA requirement included in the auth response of the login request.
|
||||
|
||||
- `mfa_payload` `(map<string|[]string>: <required>)` - A map of login MFA methodIDs to passcode credentials.
|
||||
MFA methodIDs are UUID strings which are used as keys of the map. The values of the map are
|
||||
string slices. In cases where an MFA method is configured not to use passcodes, the passcode remains an empty string.
|
||||
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
|
||||
"mfa_payload": {
|
||||
"d16fd3c2-50de-0b9b-eed3-0301dadeca10": ["910201"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
http://127.0.0.1:8200/v1/sys/mfa/validate
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
In cases where MFA validation fails, a 403 status code is returned with
|
||||
the details about the error.
|
||||
If MFA validation succeeds, the response is identical to a successful
|
||||
login request which contains a client token and its accessor.
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "7e7dec1d-311a-ecbd-4dd0-ff12a5e38959",
|
||||
"lease_id": "",
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"data": null,
|
||||
"warnings": null,
|
||||
"auth": {
|
||||
"client_token": "hvs.CAESIKZJNqQbG9E9cQGPXh68NWxi3xp7yPa1Z1RWv1P9UyHVGh4KHGh2cy5GUmYzTzdJOWhIZGFNSm5jdTBsSVNFSTk",
|
||||
"accessor": "3fBgbEmHyA5IWABmVEjqManI",
|
||||
"policies": [
|
||||
"default"
|
||||
],
|
||||
"token_policies": [
|
||||
"default"
|
||||
],
|
||||
"identity_policies": null,
|
||||
"metadata": {
|
||||
"username": "alice"
|
||||
},
|
||||
"orphan": true,
|
||||
"entity_id": "caeac75b-dbfe-58be-e3fc-957549b7292e",
|
||||
"lease_duration": 2764800,
|
||||
"renewable": true,
|
||||
"mfa_requirement": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Multi-Factor Authentication (MFA) for Login - Auth Methods
|
||||
description: |-
|
||||
Multi-factor authentication (MFA) is supported for several authentication
|
||||
methods.
|
||||
---
|
||||
# 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](/docs/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
|
||||
|
||||
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](/api/secret/identity/mfa) 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](/api/secret/identity/mfa/login-enforcement)
|
||||
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.
|
||||
|
||||
Although an MFA method configuration , such as Okta, Duo, and PingID, needs a mount accessor and an MFA enforcement configuration
|
||||
could use mount accessors, these two accessors do not necessarily need to be the same.
|
||||
However, a user trying to log in on an MFA enforced mount needs to have an alias on the accessor in the MFA method itself.
|
||||
In this case, the entity/alias templating must render out the username associated third party account.
|
||||
|
||||
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 embeds 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
|
||||
|
||||
```shell-session
|
||||
$ 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.
|
||||
|
||||
```shell-session
|
||||
$ 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
|
||||
|
||||
```json
|
||||
{
|
||||
"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](/api/secret/identity/mfa/duo) 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](/api/system/mfa/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
|
||||
|
||||
```json
|
||||
{
|
||||
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
|
||||
"mfa_payload": {
|
||||
"d16fd3c2-50de-0b9b-eed3-0301dadeca10": ["910201"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample Request
|
||||
|
||||
```shell-session
|
||||
$ 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.
|
||||
|
||||
```shell-session
|
||||
$ 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.
|
||||
|
||||
```shell-session
|
||||
$ vault write -non-interactive sys/mfa/validate -format=json @payload.json
|
||||
```
|
||||
|
|
@ -508,6 +508,10 @@
|
|||
{
|
||||
"title": "<code>/sys/mfa/method/totp</code>",
|
||||
"path": "system/mfa/totp"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/mfa/validate</code>",
|
||||
"path": "system/mfa/validate"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -1209,6 +1209,10 @@
|
|||
"title": "LDAP",
|
||||
"path": "auth/ldap"
|
||||
},
|
||||
{
|
||||
"title": "Login MFA",
|
||||
"path": "auth/login-mfa"
|
||||
},
|
||||
{
|
||||
"title": "Oracle Cloud Infrastructure",
|
||||
"path": "auth/oci"
|
||||
|
|
|
|||
Loading…
Reference in New Issue