From 4c579191fb4ef03f3e897ac752e45430870a0f2c Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 7 Mar 2022 11:44:15 -0800 Subject: [PATCH] MFA docs for config endpoints (#14302) --- .../api-docs/secret/identity/index.mdx | 2 + .../api-docs/secret/identity/mfa/duo.mdx | 162 ++++++++++ .../api-docs/secret/identity/mfa/index.mdx | 26 ++ .../secret/identity/mfa/login-enforcement.mdx | 153 ++++++++++ .../api-docs/secret/identity/mfa/okta.mdx | 157 ++++++++++ .../api-docs/secret/identity/mfa/pingid.mdx | 152 ++++++++++ .../api-docs/secret/identity/mfa/totp.mdx | 283 ++++++++++++++++++ website/data/api-docs-nav-data.json | 29 ++ 8 files changed, 964 insertions(+) create mode 100644 website/content/api-docs/secret/identity/mfa/duo.mdx create mode 100644 website/content/api-docs/secret/identity/mfa/index.mdx create mode 100644 website/content/api-docs/secret/identity/mfa/login-enforcement.mdx create mode 100644 website/content/api-docs/secret/identity/mfa/okta.mdx create mode 100644 website/content/api-docs/secret/identity/mfa/pingid.mdx create mode 100644 website/content/api-docs/secret/identity/mfa/totp.mdx diff --git a/website/content/api-docs/secret/identity/index.mdx b/website/content/api-docs/secret/identity/index.mdx index f647d47315..2c5f20bebb 100644 --- a/website/content/api-docs/secret/identity/index.mdx +++ b/website/content/api-docs/secret/identity/index.mdx @@ -18,3 +18,5 @@ see the [Vault Identity documentation](/docs/secrets/identity). - [Group Alias](/api-docs/secret/identity/group-alias) - [Identity Tokens](/api-docs/secret/identity/tokens) - [Lookup](/api-docs/secret/identity/lookup) +- [OIDC Provider](/api-docs/secret/identity/oidc-provider) +- [MFA](/api-docs/secret/identity/mfa) diff --git a/website/content/api-docs/secret/identity/mfa/duo.mdx b/website/content/api-docs/secret/identity/mfa/duo.mdx new file mode 100644 index 0000000000..18f71ccccb --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/duo.mdx @@ -0,0 +1,162 @@ +--- +layout: api +page_title: /identity/mfa/method/duo - HTTP API +description: >- + The '/identity/mfa/method/duo' endpoint focuses on managing Duo MFA behaviors in Vault. +--- + +## Configure Duo MFA Method + +This endpoint defines an MFA method of type Duo. + +| Method | Path | +| :----- |:-------------------------------| +| `POST` | `/identity/mfa/method/duo/:id` | + +### Parameters + +- `id` `(string: "")` - Optional UUID to specify if updating an existing method. + +- `mount_accessor` `(string: )` - The mount to tie this method to for use in automatic mappings. The mapping +uses the Name field of Aliases associated with this mount as the username in the mapping. This can + be from the current namespace or a child namespace. + +- `username_format` `(string)` - A format string for mapping Identity names to MFA methods. Values to substitute should be placed in `{{}}`. For example, `"{{alias.name}}@example.com"`. If blank, the Alias's Name field is used as-is. Currently-supported mappings: + + - alias.name: The name returned by the mount configured via the `mount_accessor` parameter + - entity.name: The name configured for the Entity + - alias.metadata.``: The value of the Alias's metadata parameter + - entity.metadata.``: The value of the Entity's metadata parameter + +- `secret_key` `(string: )` - Secret key for Duo. + +- `integration_key` `(string: )` - Integration key for Duo. + +- `api_hostname` `(string: )` - API hostname 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. + +### Sample Payload + +```json +{ + "mount_accessor": "auth_userpass_1793464a", + "secret_key": "BIACEUEAXI20BNWTEYXT", + "integration_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz", + "api_hostname": "api-2b5c39f5.duosecurity.com" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d +``` + +## Read Duo MFA Method + +This endpoint queries the MFA configuration of Duo type for a given method +ID. + +| Method | Path | +| :----- |:-------------------------------| +| `GET` | `/identity/mfa/method/duo/:id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +```json +{ + "data": { + "api_hostname": "api-2b5c39f5.duosecurity.com", + "id": "4194659f-139b-400b-b5dd-86bfb726759d", + "integration_key": "BIACEUEAXI20BNWTEYXT", + "mount_accessor": "auth_userpass_1793464a", + "pushinfo": "", + "secret_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz", + "type": "duo", + "username_format": "", + "use_passcode": false + } +} +``` + +## Delete Duo MFA Method + +This endpoint deletes a Duo MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/api/secret/identity/mfa/login-enforcement). + +| Method | Path | +| :------- |:-------------------------------| +| `DELETE` | `/identity/mfa/method/duo/:id` | + +### Parameters + +- `id` `(string: )` - UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +This endpoint lists Duo MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:---------------------------| +| `LIST` | `/identity/mfa/method/duo` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo + +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "4194659f-139b-400b-b5dd-86bfb726759d" + ] + } +} +``` diff --git a/website/content/api-docs/secret/identity/mfa/index.mdx b/website/content/api-docs/secret/identity/mfa/index.mdx new file mode 100644 index 0000000000..4ef7bae6ba --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/index.mdx @@ -0,0 +1,26 @@ +--- +layout: api +page_title: /identity/mfa - HTTP API +description: >- + The '/identity/mfa' endpoint focuses on managing login MFA behaviors in Vault. +--- + +# `/identity/mfa` + +## Supported MFA types. + +- [TOTP](/api/secret/identity/mfa/totp) + +- [Okta](/api/secret/identity/mfa/okta) + +- [Duo](/api/secret/identity/mfa/duo) + +- [PingID](/api/secret/identity/mfa/pingid) + +## Other + +- [Login Enforcement](/api/secret/identity/mfa/login-enforcement) + +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 +namespaces. In the open source version of Vault, everything operates in the root namespace. diff --git a/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx b/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx new file mode 100644 index 0000000000..f64a538d5d --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/login-enforcement.mdx @@ -0,0 +1,153 @@ +--- +layout: api +page_title: /identity/mfa/login-enforcement - HTTP API +description: >- + The '/identity/mfa/login-enforcement' endpoint focuses on specifying which MFA methods should be used + when logging in. +--- + +## Create a login enforcement + +This endpoint creates or updates a login enforcement that specifies which MFA methods should be used when logging into +Vault. If there are multiple login enforcements, each one needs to be satisfied before a login attempt succeeds. + +| Method | Path | +| :----- |:----------------------------------------| +| `POST` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` - Name for this login enforcement configuration. + +- `mfa_method_ids` `([]string: )` - Array of MFA method UUIDs to use. These will be ORed together, meaning +if several IDs are specified, any one of them is sufficient to login. + +- `auth_method_accessors` `([]string: [])` - Array of auth mount accessor IDs. If present, only auth methods +corresponding to the given accessors are checked during login. + +- `auth_method_types` `([]string: [])` - Array of auth method types. If present, only auth methods +corresponding to the given types are checked during login. + +- `identity_group_ids` `([]string: [])` - Array of identity group IDs. If present, only entities belonging +to one of the given groups are checked during login. Note that these IDs can be from the current namespace or +a child namespace. + +- `identity_entity_ids` `([]string: [])` - Array of identity entity IDs. If present, only entities with the given +IDs are checked during login. Note that these IDs can be from the current namespace or a child namespace. + +Note that while none of `auth_method_accessors`, `auth_method_types`, `identity_group_ids`, or `identity_entity_ids` is +individually required, at least one of those four fields must be present to create a login enforcement. + +### Sample Payload + +```json +{ + "mfa_method_ids": ["134f7ce9-feae-4c6c-9ed7-ab3e413dbfce"], + "auth_method_accessors": ["auth_userpass_337fdb6a"] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo +``` + +## Read Login Enforcement + +This endpoint reads the login enforcement configuration for a given name. + +| Method | Path | +| :----- |:----------------------------------------| +| `GET` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` – Name of the login enforcement. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo + +``` + +### Sample Response + +```json +{ + "data": { + "auth_method_accessors": [ + "auth_userpass_337fdb6a" + ], + "auth_method_types": [], + "id": "24167a6c-759a-c596-6d48-391c89c4befc", + "identity_entity_ids": [], + "identity_group_ids": [], + "mfa_method_ids": [ + "c1372abf-bf64-1f26-c2a4-cbcfa135b775" + ], + "name": "foo", + "namespace_id": "root" + } +} +``` + +## Delete Login Enforcement + +This endpoint deletes a login enforcement configuration by the given name. + +| Method | Path | +| :------- |:----------------------------------------| +| `DELETE` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` - Name of the login enforcement. + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo + +``` + +## List Login Enforcements + +This endpoint lists login enforcements that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:----------------------------------| +| `LIST` | `/identity/mfa/login-enforcement` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement + +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "foo" + ] + } +} +``` diff --git a/website/content/api-docs/secret/identity/mfa/okta.mdx b/website/content/api-docs/secret/identity/mfa/okta.mdx new file mode 100644 index 0000000000..1e75f16493 --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/okta.mdx @@ -0,0 +1,157 @@ +--- +layout: api +page_title: /identity/mfa/method/okta - HTTP API +description: >- + The '/identity/mfa/method/okta' endpoint focuses on managing Okta MFA behaviors in Vault. +--- + +## Configure Okta MFA Method + +This endpoint defines an MFA method of type Okta. + +| Method | Path | +| :----- |:--------------------------------| +| `POST` | `/identity/mfa/method/okta/:id` | + +### Parameters + +- `id` `(string: "")` - Optional UUID to specify if updating an existing method. + +- `mount_accessor` `(string: )` - The mount to tie this method to for use in automatic mappings. The mapping + will use the Name field of Aliases associated with this mount as the username in the mapping. Note that this can + be from the current namespace or a child namespace. + +- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{alias.name}}@example.com"`. If blank, the Alias's Name field is used as-is. Currently-supported mappings: + + - alias.name: The name returned by the mount configured via the `mount_accessor` parameter + - entity.name: The name configured for the Entity + - alias.metadata.``: The value of the Alias's metadata parameter + - entity.metadata.``: The value of the Entity's metadata parameter + +- `org_name` `(string: )` - Name of the organization to be used in the Okta API. + +- `api_token` `(string: )` - Okta API key. + +- `base_url` `(string)` - If set, will be used as the base domain for API requests. Examples are okta.com, oktapreview.com, and okta-emea.com. + +- `primary_email` `(bool: false)` - If set, the username will only match the primary email for the account. + +### Sample Payload + +```json +{ + "mount_accessor": "auth_userpass_1793464a", + "org_name": "dev-262778", + "api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc +``` + +## Read Okta MFA Method + +This endpoint queries the MFA configuration of Okta type for a given method +name. + +| Method | Path | +| :----- |:--------------------------------| +| `GET` | `/identity/mfa/method/okta/:id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +```json +{ + "data": { + "api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC", + "id": "1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc", + "mount_accessor": "auth_userpass_1793464a", + "name": "my_okta", + "org_name": "dev-262778", + "type": "okta", + "username_format": "" + } +} +``` + +## Delete Okta MFA Method + +This endpoint deletes a Okta MFA method. The MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/api/secret/identity/mfa/login-enforcement). + +| Method | Path | +| :------- |:--------------------------------| +| `DELETE` | `/identity/mfa/method/okta/:id` | + +### Parameters + +- `id` `(string: )` - UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +This endpoint lists Okta MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:----------------------------| +| `LIST` | `/identity/mfa/method/okta` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta + +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc" + ] + } +} +``` diff --git a/website/content/api-docs/secret/identity/mfa/pingid.mdx b/website/content/api-docs/secret/identity/mfa/pingid.mdx new file mode 100644 index 0000000000..5bc2c1cf01 --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/pingid.mdx @@ -0,0 +1,152 @@ +--- +layout: api +page_title: /identity/mfa/method/pingid - HTTP API +description: >- + The '/identity/mfa/method/pingid' endpoint focuses on managing PingID MFA behaviors in Vault. +--- + +## Configure PingID MFA Method + +This endpoint defines an MFA method of type PingID. + +| Method | Path | +| :----- |:----------------------------------| +| `POST` | `/identity/mfa/method/pingid/:id` | + +### Parameters + +- `id` `(string: "")` - Optional UUID to specify if updating an existing method. + +- `mount_accessor` `(string: )` - The mount to tie this method to for use in automatic mappings. The mapping + will use the Name field of Aliases associated with this mount as the username in the mapping. Note that this can + be from the current namespace or a child namespace. + +- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{alias.name}}@example.com"`. If blank, the Alias's Name field is used as-is. Currently-supported mappings: + + - alias.name: The name returned by the mount configured via the `mount_accessor` parameter + - entity.name: The name configured for the Entity + - alias.metadata.``: The value of the Alias's metadata parameter + - entity.metadata.``: The value of the Entity's metadata parameter + +- `settings_file_base64` `(string: )` - A base64-encoded third-party settings file retrieved from PingID's configuration page. + +### Sample Payload + +```json +{ + "mount_accessor": "auth_userpass_1793464a", + "settings_file_base64": "AA8owj3..." +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 +``` + +## Read PingID MFA Method + +This endpoint queries the MFA configuration of PingID type for a given method +name. + +| Method | Path | +| :----- |:----------------------------------| +| `GET` | `/identity/mfa/method/pingid/:id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +```json +{ + "data": { + "use_signature": true, + "idp_url": "https://idpxnyl3m.pingidentity.com/pingid", + "admin_url": "https://idpxnyl3m.pingidentity.com/pingid", + "authenticator_url": "https://authenticator.pingone.com/pingid/ppm", + "mount_accessor": "auth_userpass_1793464a", + "id": "f8381105-67f0-4105-8662-4b07ae5c1233", + "org_alias": "181459b0-9fb1-4938-8c86...", + "type": "pingid", + "username_format": "" + } +} +``` + +## Delete PingID MFA Method + +This endpoint deletes a PingID MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/api/secret/identity/mfa/login-enforcement). + +| Method | Path | +| :------- |:----------------------------------| +| `DELETE` | `/identity/mfa/method/pingid/:id` | + +### Parameters + +- `id` `(string: )` - UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +This endpoint lists PingID MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:------------------------------| +| `LIST` | `/identity/mfa/method/pingid` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid + +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "f8381105-67f0-4105-8662-4b07ae5c1233" + ] + } +} +``` diff --git a/website/content/api-docs/secret/identity/mfa/totp.mdx b/website/content/api-docs/secret/identity/mfa/totp.mdx new file mode 100644 index 0000000000..bfd255bf22 --- /dev/null +++ b/website/content/api-docs/secret/identity/mfa/totp.mdx @@ -0,0 +1,283 @@ +--- +layout: api +page_title: /identity/mfa/method/totp - HTTP API +description: >- + The '/identity/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in Vault. +--- + +## Configure TOTP MFA Method + +This endpoint defines an MFA method of type TOTP. + +| Method | Path | +| :----- |:--------------------------------| +| `POST` | `/identity/mfa/method/totp/:id` | + +### Parameters + +- `id` `(string: "")` - Optional UUID to specify if updating an existing method. + +- `issuer` `(string: )` - The name of the key's issuing organization. + +- `period` `(int or duration format string: 30)` - The length of time used to generate a counter for the TOTP token calculation. + +- `key_size` `(int: 20)` – Specifies the size in bytes of the generated key. + +- `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". + +- `digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8. + +- `skew` `(int: 1)` - The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1. + +### Sample Payload + +```json +{ + "issuer": "vault" +} +``` + +### 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 +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/1f36d4cf-52c9-475d-a5cd-49c573c54e55 +``` + +## Read TOTP MFA Method + +This endpoint queries the MFA configuration of TOTP type for a given method +ID. + +| Method | Path | +| :----- |:--------------------------------| +| `GET` | `/identity/mfa/method/totp/:id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +```json +{ + "data": { + "algorithm": "SHA1", + "digits": 6, + "id": "4c6b1968-b385-4c46-ac5e-9b74e7b206be", + "issuer": "vault", + "key_size": 20, + "period": 30, + "qr_size": 200, + "skew": 1, + "type": "totp", + "namespace": "" + } +} +``` + +## Delete TOTP MFA Method + +This endpoint deletes a TOTP MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/api/secret/identity/mfa/login-enforcement). + +| Method | Path | +| :------- |:--------------------------------| +| `DELETE` | `/identity/mfa/method/totp/:id` | + +### Parameters + +- `id` `(string: )` - UUID of the MFA method. + +### Sample Request + +```shell-session +$ 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 + +This endpoint lists TOTP MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:--------------------------------| +| `LIST` | `/identity/mfa/method/totp` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp + +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "1f36d4cf-52c9-475d-a5cd-49c573c54e55", + "4c6b1968-b385-4c46-ac5e-9b74e7b206be" + ] + } +} +``` + +## Generate a TOTP MFA Secret + +This endpoint generates an MFA secret in the entity of the calling token, if it +doesn't exist already, using the configuration stored under the given MFA +method ID. + +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/identity/mfa/method/totp/generate` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Sample Payload + +```json +{ + "method_id": "1f36d4cf-52c9-475d-a5cd-49c573c54e55" +} +``` + +### 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/generate +``` + +### Sample Response + +```json +{ + "data": { + "barcode": "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 rkJggg==", + "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=XVE7TOZWJVEWQOATOD7 U53IEAJG72Z2I" + } +} +``` + +## Administratively Generate a TOTP MFA Secret + +This endpoint can be used to generate a TOTP MFA secret. Unlike the `generate` +API which stores the generated secret on the entity ID of the calling token, +the `admin-generate` API stores the generated secret on the given entity ID. + +| Method | Path | +| :----- |:-------------------------------------------------| +| `POST` | `/identity/mfa/method/totp/admin-generate` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- `entity_id` `(string: )` - Entity ID on which the generated secret + needs to get stored. + +### Sample Payload + +```json +{ + "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4", + "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01" +} +``` + +### 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/admin-generate +``` + +### Sample Response + +```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" + } +} +``` + +### Administratively Destroy TOTP MFA Secret + +This endpoint deletes a TOTP MFA secret from the given entity ID. + +To overwrite a secret on the entity, +explicitly deleting the secret first is required. This API can be used to delete the secret +and the `generate` or `admin-generate` APIs should be used to regenerate a new +secret. + +| Method | Path | +| :----- |:------------------------------------------| +| `POST` | `/identity/mfa/method/totp/admin-destroy` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- `entity_id` `(string: )` - Entity ID from which the MFA secret + should be removed. + +### Sample Payload + +```json +{ + "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4", + "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01" +} +``` + +### 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/admin-destroy +``` diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 9b571d9e6a..1b191b5c28 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -195,6 +195,35 @@ { "title": "OIDC Provider", "path": "secret/identity/oidc-provider" + }, + { + "title": "MFA", + "routes": [ + { + "title": "Overview", + "path": "secret/identity/mfa" + }, + { + "title": "Duo", + "path": "secret/identity/mfa/duo" + }, + { + "title": "Okta", + "path": "secret/identity/mfa/okta" + }, + { + "title": "PingID", + "path": "secret/identity/mfa/pingid" + }, + { + "title": "TOTP", + "path": "secret/identity/mfa/totp" + }, + { + "title": "Login Enforcement", + "path": "secret/identity/mfa/login-enforcement" + } + ] } ] },