1.21 - RC Add MFA TOTP Self-Enroll Docs #1041
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -13,7 +13,7 @@ This endpoint creates an MFA method of type TOTP. | |
| |:-------|:----------------------------| | ||
| | `POST` | `/identity/mfa/method/totp` | | ||
|
|
||
| ### Request parameters | ||
|
|
||
| - `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0. | ||
|
|
||
|
|
@@ -33,6 +33,9 @@ This endpoint creates an MFA method of type TOTP. | |
|
|
||
| - `max_validation_attempts` `(int: 5)` - The maximum number of consecutive failed validation attempts. | ||
|
|
||
| - `enable_self_enrollment` `(bool: false)` - <EnterpriseAlert product="vault" inline /> When enabled, allows users to setup TOTP for their account by generating | ||
| a TOTP secret (QR code) during login if they do not already have one. | ||
|
|
||
| ### Sample payload | ||
|
|
||
| ```json | ||
|
|
@@ -59,11 +62,13 @@ This endpoint updates the configuration of an MFA method of type TOTP. | |
| |:-------|:---------------------------------------| | ||
| | `POST` | `/identity/mfa/method/totp/:method_id` | | ||
|
|
||
| ### Path parameters | ||
|
|
||
| - `method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
| ### Request parameters | ||
|
|
||
| All of the parameters documented under the preceding ["Create"](#create-totp-mfa-method) endpoint. | ||
|
|
||
| ### Sample payload | ||
|
|
||
|
|
@@ -88,7 +93,7 @@ ID. | |
| |:-------|:---------------------------------------| | ||
| | `GET` | `/identity/mfa/method/totp/:method_id` | | ||
|
|
||
| ### Path parameters | ||
|
|
||
| - `method_id` `(string: <required>)` – UUID of the MFA method. | ||
|
|
||
|
|
@@ -129,7 +134,7 @@ by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). | |
| |:---------|:---------------------------------------| | ||
| | `DELETE` | `/identity/mfa/method/totp/:method_id` | | ||
|
|
||
| ### Path parameters | ||
|
|
||
| - `method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
|
|
@@ -182,7 +187,7 @@ method ID. | |
| |:-------|:-------------------------------------| | ||
| | `POST` | `/identity/mfa/method/totp/generate` | | ||
|
|
||
| ### Request parameters | ||
|
|
||
| - `method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
|
|
@@ -225,7 +230,7 @@ the `admin-generate` API stores the generated secret on the given entity ID. | |
| |:-------|:-------------------------------------------| | ||
| | `POST` | `/identity/mfa/method/totp/admin-generate` | | ||
|
|
||
| ### Request parameters | ||
|
|
||
| - `method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
|
|
@@ -275,7 +280,7 @@ secret. | |
| |:-------|:------------------------------------------| | ||
| | `POST` | `/identity/mfa/method/totp/admin-destroy` | | ||
|
|
||
| ### Request parameters | ||
|
|
||
| - `method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
|
|
@@ -300,3 +305,51 @@ $ curl \ | |
| --data @payload.json \ | ||
| http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-destroy | ||
| ``` | ||
|
|
||
| ## Self-enroll in TOTP MFA <EnterpriseAlert product="vault" inline /> | ||
|
|
||
| The self-enroll endpoint lets users setup TOTP MFA by generating a TOTP | ||
| secret (QR code) during login if they do not already have one. To use | ||
| self-enrollment you must set [`enable_self_enrollment`](./totp#enable_self_enrollment) to `true` for the TOTP MFA | ||
| method. | ||
|
|
||
| | Method | Path | | ||
| |:-------|:----------------------------------------| | ||
| | `POST` | `/identity/mfa/method/totp/self-enroll` | | ||
|
There was a problem hiding this comment. Do you think it's worth mentioning somewhere that the UI only enters the self-enroll workflow if only one enforcement is configured because that's when Technically, users could circumvent this by manually requesting There was a problem hiding this comment. Very good point, I completely forgot about that. Yes, I think we should mention it wherever we can as long as this makes sense, to avoid users being confused. Maybe it would make sense to add screenshots of the whole flow somewhere? 🤔 There was a problem hiding this comment. Yeah - I was holding off on screenshots until I heard back from the education team (since I just took a best guess at where to add docs 😂 ) But yes - @schavis - do you have thoughts on:
There was a problem hiding this comment. I'm not sure what happened to my original reply from last night =\
In general, we try to limit the number of screenshots due to the maintenance burden. Is there a "hero" screenshot we can reference to help folks orient themselves in the GUI?
Since we're essentially calling out a configuration gotcha, I'd recommend adding it as part of the instructions under "Option 1: Configure TOTP for self-enrollment". There was a problem hiding this comment. The QR code appears after the user logs in, so I'm not sure that it would provide much of a benefit. I'm thinking we can add it later, if we think it'd be helpful, but for now I don't think it's necessary. I'll add below! |
||
|
|
||
| ### Request parameters | ||
|
|
||
| - `mfa_request_id` `(string: <required>)` - The unique identifier of an MFA | ||
| requirement in the authentication response of a login request. | ||
|
|
||
| - `mfa_method_id` `(string: <required>)` - UUID of the MFA method. | ||
|
|
||
| ### Sample payload | ||
|
|
||
| ```json | ||
| { | ||
| "mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7", | ||
| "mfa_method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4" | ||
| } | ||
| ``` | ||
|
|
||
| ### Sample request | ||
|
|
||
| ```shell-session | ||
| $ curl \ | ||
| --header "X-Vault-Token: ..." \ | ||
| --request POST \ | ||
| --data @payload.json \ | ||
| http://127.0.0.1:8200/v1/identity/mfa/method/totp/self-enroll | ||
| ``` | ||
|
|
||
| ### Sample response | ||
|
There was a problem hiding this comment. Added this, contents is copy/pasted from the sample output above |
||
|
|
||
| ```json | ||
| { | ||
| "data": { | ||
| "barcode": "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", | ||
| "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U" | ||
| } | ||
| } | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| ### vault.replication.rpc.client.persist_pending_login_mfa_secret ((#vault-replication-rpc-client-persist_pending_login_mfa_secret)) | ||
|
|
||
| Metric type | Value | Description | ||
| ----------- | ----- | ----------- | ||
| summary | ms | Time required by the client to persist the pending login MFA TOTP secret |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| ### vault.replication.rpc.server.persist_pending_login_mfa_secret ((#vault-replication-rpc-server-persist_pending_login_mfa_secret)) | ||
|
|
||
| Metric type | Value | Description | ||
| ----------- | ----- | ----------- | ||
| summary | ms | Time required by the server to persist the pending login MFA TOTP secret |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Increased this header size so it is now included in the page table of contents