luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

docs for named login MFA (#18833) 

* docs for named login MFA

* feedback
This commit is contained in:
Hamid Ghaf 2023-02-01 10:30:14 -05:00 committed by GitHub
parent 5d17f9b142
commit 6a8716ac18
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 68 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
website/content/api-docs/secret/identity/mfa/duo.mdx
View File

@ -11,11 +11,13 @@ This endpoint defines an MFA method of type Duo.
| Method | Path | | Method | Path |
| :----- | :----------------------------- | | :----- | :----------------------------- |
| `POST` | `/identity/mfa/method/duo/:id` | | `POST` | `/identity/mfa/method/duo/:method_id` |
### Parameters ### Parameters
- `id` `(string: "")` - Optional UUID to specify if updating an existing method. - `method_id` `(string: "")` - Optional UUID to specify if updating an existing method.
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A template string for mapping Identity names to MFA methods. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}"`. If blank, the Entity's Name field is used as-is. - `username_format` `(string)` - A template string for mapping Identity names to MFA methods. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}"`. If blank, the Entity's Name field is used as-is.
@ -27,8 +29,6 @@ This endpoint defines an MFA method of type Duo.
- `push_info` `(string)` - Push information for Duo. - `push_info` `(string)` - Push information for Duo.
-
- `use_passcode` `(bool: false)` - If true, the user is reminded to use the passcode upon MFA validation. - `use_passcode` `(bool: false)` - If true, the user is reminded to use the passcode upon MFA validation.
### Sample Payload ### Sample Payload
@ -38,7 +38,8 @@ This endpoint defines an MFA method of type Duo.
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}", "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"secret_key": "BIACEUEAXI20BNWTEYXT", "secret_key": "BIACEUEAXI20BNWTEYXT",
"integration_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz", "integration_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz",
"api_hostname": "api-2b5c39f5.duosecurity.com" "api_hostname": "api-2b5c39f5.duosecurity.com",
"method_name": "ns1_duo",
} }
``` ```
@ -80,7 +81,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
``` ```
### Sample Response ### Sample Response
@ -120,7 +120,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request DELETE \ --request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
``` ```
## List Duo MFA Methods ## List Duo MFA Methods
@ -138,7 +137,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request LIST \ --request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/duo http://127.0.0.1:8200/v1/identity/mfa/method/duo
``` ```
### Sample Response ### Sample Response

9
website/content/api-docs/secret/identity/mfa/okta.mdx
View File

@ -11,11 +11,13 @@ This endpoint defines an MFA method of type Okta.
| Method | Path | | Method | Path |
| :----- | :------------------------------ | | :----- | :------------------------------ |
| `POST` | `/identity/mfa/method/okta/:id` | | `POST` | `/identity/mfa/method/okta/:method_id` |
### Parameters ### Parameters
- `id` `(string: "")` - Optional UUID to specify if updating an existing method. - `method_id` `(string: "")` - Optional UUID to specify if updating an existing method.
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is. - `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is.
@ -75,7 +77,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
``` ```
### Sample Response ### Sample Response
@ -113,7 +114,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request DELETE \ --request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
``` ```
## List Okta MFA Methods ## List Okta MFA Methods
@ -131,7 +131,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request LIST \ --request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/okta http://127.0.0.1:8200/v1/identity/mfa/method/okta
``` ```
### Sample Response ### Sample Response

9
website/content/api-docs/secret/identity/mfa/pingid.mdx
View File

@ -11,11 +11,13 @@ This endpoint defines an MFA method of type PingID.
| Method | Path | | Method | Path |
| :----- | :-------------------------------- | | :----- | :-------------------------------- |
| `POST` | `/identity/mfa/method/pingid/:id` | | `POST` | `/identity/mfa/method/pingid/:method_id` |
### Parameters ### Parameters
- `id` `(string: "")` - Optional UUID to specify if updating an existing method. - `method_id` `(string: "")` - Optional UUID to specify if updating an existing method.
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `username_format` `(string)` - A template string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is. - `username_format` `(string)` - A template string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is.
@ -68,7 +70,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
``` ```
### Sample Response ### Sample Response
@ -107,7 +108,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request DELETE \ --request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
``` ```
## List PingID MFA Methods ## List PingID MFA Methods
@ -125,7 +125,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request LIST \ --request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid http://127.0.0.1:8200/v1/identity/mfa/method/pingid
``` ```
### Sample Response ### Sample Response

11
website/content/api-docs/secret/identity/mfa/totp.mdx
View File

@ -11,11 +11,13 @@ This endpoint defines an MFA method of type TOTP.
| Method | Path | | Method | Path |
| :----- | :------------------------------ | | :----- | :------------------------------ |
| `POST` | `/identity/mfa/method/totp/:id` | | `POST` | `/identity/mfa/method/totp/:method_id` |
### Parameters ### Parameters
- `id` `(string: "")` - Optional UUID to specify if updating an existing method. - `method_id` `(string: "")` - Optional UUID to specify if updating an existing method.
- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0.
- `issuer` `(string: <required>)` - The name of the key's issuing organization. - `issuer` `(string: <required>)` - The name of the key's issuing organization.
@ -25,7 +27,7 @@ This endpoint defines an MFA method of type TOTP.
- `qr_size` `(int: 200)` - The pixel size of the generated square QR code. - `qr_size` `(int: 200)` - The pixel size of the generated square QR code.
- `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512". - `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".
- `digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8. - `digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8.
@ -79,7 +81,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request GET \ --request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
``` ```
### Sample Response ### Sample Response
@ -121,7 +122,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request DELETE \ --request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
``` ```
## List TOTP MFA Methods ## List TOTP MFA Methods
@ -139,7 +139,6 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request LIST \ --request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/totp http://127.0.0.1:8200/v1/identity/mfa/method/totp
``` ```
### Sample Response ### Sample Response

11
website/content/api-docs/system/mfa/validate.mdx
View File

@ -35,6 +35,17 @@ string slices. In cases where an MFA method is configured not to use passcodes,
} }
``` ```
As of Vault 1.13.0, it is also possible to use an MFA method name as the key to the `mfa_payload`.
In versions 1.12.x and below,`passcode=` was used for Duo MFA only. Starting in version 1.13.x, `passcode=` is optional for all supported MFA methods.
```json
{
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
"mfa_payload": {
"sample_mfa_method_name": ["passcode=910201"]
}
}
### Sample Request ### Sample Request
```shell-session ```shell-session

41
website/content/docs/auth/login-mfa/index.mdx
View File

@ -62,8 +62,10 @@ In the Single-phase login, the required MFA information is embedded in a login r
the `X-Vault-MFA` header. In this case, the MFA validation is done the `X-Vault-MFA` header. In this case, the MFA validation is done
as a part of the login request. as a part of the login request.
MFA credentials are retrieved from the `X-Vault-MFA` HTTP header. The format of MFA credentials are retrieved from the `X-Vault-MFA` HTTP header. Before Vault 1.13.0, 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. the header is `mfa_method_id[:passcode]` for TOTP, Okta, and PingID. However, for Duo, it is `mfa_method_id[:passcode=<passcode>]`.
The item in the `[]` is optional. From Vault 1.13.0, the format is consistent for all supported MFA methods, and one can use either of the above two formats.
If there are multiple MFA methods that need to be validated, a user can pass in multiple `X-Vault-MFA` HTTP headers.
#### Sample Request #### Sample Request
@ -83,6 +85,27 @@ If an MFA method does not require a passcode, the login request MFA header only
http://127.0.0.1:8200/v1/auth/userpass/login/alice http://127.0.0.1:8200/v1/auth/userpass/login/alice
``` ```
Starting in Vault 1.13.0, an operator can configure a name for an MFA method.
This name should be unique in the namespace in which the MFA method is configured.
The MFA method name can be used in the MFA header.
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: sample_mfa_method_name:695452" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
```
In cases where the MFA method is configured in a specific namespace, the MFA method name should be prefixed with the namespace path.
Below shows an example where an MFA method is configured in `ns1`.
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: ns1/sample_mfa_method_name:695452" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
```
### Two-Phase Login ### Two-Phase Login
The more conventional and prevalent MFA method is a two-request mechanism, also referred to as Two-phase Login MFA. The more conventional and prevalent MFA method is a two-request mechanism, also referred to as Two-phase Login MFA.
@ -125,7 +148,8 @@ note that this can affect the login response on any auth mount protected by MFA
{ {
"type": "totp", "type": "totp",
"id": "820997b3-110e-c251-7e8b-ff4aa428a6e1", "id": "820997b3-110e-c251-7e8b-ff4aa428a6e1",
"uses_passcode": true "uses_passcode": true,
"name": "sample_mfa_method_name",
} }
] ]
} }
@ -156,6 +180,17 @@ credentials will be a list with one empty string.
} }
``` ```
If an MFA method is configured in a namespace, the MFA method name prefixed with the namespace path can be used in the validation payload.
```json
{
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
"mfa_payload": {
"ns1/sample_mfa_method_name": ["910201"]
}
}
```
#### Sample Request #### Sample Request
```shell-session ```shell-session