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 |
| :----- | :----------------------------- |
| `POST` | `/identity/mfa/method/duo/:id` |
| `POST` | `/identity/mfa/method/duo/:method_id` |
### 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.
@ -27,8 +29,6 @@ This endpoint defines an MFA method of type 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.
### Sample Payload
@ -38,7 +38,8 @@ This endpoint defines an MFA method of type Duo.
"username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}",
"secret_key": "BIACEUEAXI20BNWTEYXT",
"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: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
```
### Sample Response
@ -120,7 +120,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d
```
## List Duo MFA Methods
@ -138,7 +137,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/duo
```
### 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 |
| :----- | :------------------------------ |
| `POST` | `/identity/mfa/method/okta/:id` |
| `POST` | `/identity/mfa/method/okta/:method_id` |
### 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.
@ -75,7 +77,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
```
### Sample Response
@ -113,7 +114,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc
```
## List Okta MFA Methods
@ -131,7 +131,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/okta
```
### 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 |
| :----- | :-------------------------------- |
| `POST` | `/identity/mfa/method/pingid/:id` |
| `POST` | `/identity/mfa/method/pingid/:method_id` |
### 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.
@ -68,7 +70,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
```
### Sample Response
@ -107,7 +108,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233
```
## List PingID MFA Methods
@ -125,7 +125,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/pingid
```
### 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 |
| :----- | :------------------------------ |
| `POST` | `/identity/mfa/method/totp/:id` |
| `POST` | `/identity/mfa/method/totp/:method_id` |
### 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.
@ -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.
- `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.
@ -79,7 +81,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
```
### Sample Response
@ -121,7 +122,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be
```
## List TOTP MFA Methods
@ -139,7 +139,6 @@ $ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/identity/mfa/method/totp
```
### 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
```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
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.
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]` 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
@ -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
```
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
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",
"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
```shell-session