docs: API docs for TOTP, Okta and Duo MFA (#3129)
* docs: API docs for TOTP, Okta and Duo MFA * docs: List types in the MFA main page
This commit is contained in:
parent
2e80e6488f
commit
9410ec2c6d
116
website/source/api/system/mfa-duo.html.md
Normal file
116
website/source/api/system/mfa-duo.html.md
Normal file
|
@ -0,0 +1,116 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "/sys/mfa/method/duo - HTTP API"
|
||||
sidebar_current: "docs-http-system-mfa-duo"
|
||||
description: |-
|
||||
The '/sys/mfa/method/duo' endpoint focuses on managing Duo MFA behaviors in Vault Enterprise.
|
||||
---
|
||||
|
||||
## Configure Duo MFA Method
|
||||
|
||||
This endpoint defines a MFA method of type Duo.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/duo/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `mount_accessor` `(string: <required>)` - The mount to tie this method to for use in automatic mappings. The mapping will use the Name field of Personas associated with this mount as the username in the mapping.
|
||||
|
||||
- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{persona.name}}@example.com"`. If blank, the Persona's Name field will be used as-is. Currently-supported mappings:
|
||||
- persona.name: The name returned by the mount configured via the `mount_accessor` 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.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"mount_accessor": "auth_userpass_1793464a",
|
||||
"secret_key": "BIACEUEAXI20BNWTEYXT",
|
||||
"integration_key":"8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz",
|
||||
"api_hostname":"api-2b5c39f5.duosecurity.com"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/mfa/method/duo/my_duo
|
||||
```
|
||||
|
||||
## Read Duo MFA Method
|
||||
|
||||
This endpoint queries the MFA configuration of Duo type for a given method
|
||||
name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/duo/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/duo/my_duo
|
||||
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"api_hostname": "api-2b5c39f5.duosecurity.com",
|
||||
"id": "0ad21b78-e9bb-64fa-88b8-1e38db217bde",
|
||||
"integration_key": "BIACEUEAXI20BNWTEYXT",
|
||||
"mount_accessor": "auth_userpass_1793464a",
|
||||
"name": "my_duo",
|
||||
"pushinfo": "",
|
||||
"secret_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz",
|
||||
"type": "duo",
|
||||
"username_format": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
## Delete Duo MFA Method
|
||||
|
||||
This endpoint deletes a Duo MFA method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `DELETE` | `/sys/mfa/method/duo/:name` | `204 (empty body)` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/mfa/method/duo/my_duo
|
||||
|
||||
```
|
112
website/source/api/system/mfa-okta.html.md
Normal file
112
website/source/api/system/mfa-okta.html.md
Normal file
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "/sys/mfa/method/okta - HTTP API"
|
||||
sidebar_current: "docs-http-system-mfa-okta"
|
||||
description: |-
|
||||
The '/sys/mfa/method/okta' endpoint focuses on managing Okta MFA behaviors in Vault Enterprise.
|
||||
---
|
||||
|
||||
## Configure Okta MFA Method
|
||||
|
||||
This endpoint defines a MFA method of type Okta.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/okta/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `mount_accessor` `(string: <required>)` - The mount to tie this method to for use in automatic mappings. The mapping will use the Name field of Personas associated with this mount as the username in the mapping.
|
||||
|
||||
- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{persona.name}}@example.com"`. If blank, the Persona's Name field will be used as-is. Currently-supported mappings:
|
||||
- persona.name: The name returned by the mount configured via the `mount_accessor` parameter
|
||||
|
||||
- `org_name` `(string)` - Name of the organization to be used in the Okta API.
|
||||
|
||||
- `api_token` `(string)` - Okta API key.
|
||||
|
||||
- `production` `(string)` - If set, production API URL prefix will be used to communicate with Okta and if not set, a preview production API URL prefix will be used. Defaults to true.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"mount_accessor": "auth_userpass_1793464a",
|
||||
"org_name": "dev-262778",
|
||||
"api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/mfa/method/okta/my_okta
|
||||
```
|
||||
|
||||
## Read Okta MFA Method
|
||||
|
||||
This endpoint queries the MFA configuration of Okta type for a given method
|
||||
name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/okta/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/okta/my_okta
|
||||
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC",
|
||||
"id": "e39f08a1-a42d-143d-5b87-15c61d89c15a",
|
||||
"mount_accessor": "auth_userpass_1793464a",
|
||||
"name": "my_okta",
|
||||
"org_name": "dev-262778",
|
||||
"production": true,
|
||||
"type": "okta",
|
||||
"username_format": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
## Delete Okta MFA Method
|
||||
|
||||
This endpoint deletes a Okta MFA method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `DELETE` | `/sys/mfa/method/okta/:name` | `204 (empty body)` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/mfa/method/okta/my_okta
|
||||
|
||||
```
|
235
website/source/api/system/mfa-totp.html.md
Normal file
235
website/source/api/system/mfa-totp.html.md
Normal file
|
@ -0,0 +1,235 @@
|
|||
---
|
||||
layout: "api"
|
||||
page_title: "/sys/mfa/method/totp - HTTP API"
|
||||
sidebar_current: "docs-http-system-mfa-totp"
|
||||
description: |-
|
||||
The '/sys/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in Vault Enterprise.
|
||||
---
|
||||
|
||||
## Configure TOTP MFA Method
|
||||
|
||||
This endpoint defines a MFA method of type TOTP.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/totp/:name` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `issuer` `(string: <required>)` - 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
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_totp
|
||||
```
|
||||
|
||||
## Read TOTP MFA Method
|
||||
|
||||
This endpoint queries the MFA configuration of TOTP type for a given method
|
||||
name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/totp/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_totp
|
||||
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"algorithm": "SHA1",
|
||||
"digits": 6,
|
||||
"id": "865587ba-6229-7f2a-6da0-609d5370af70",
|
||||
"issuer": "vault",
|
||||
"key_size": 20,
|
||||
"name": "my_totp",
|
||||
"period": 30,
|
||||
"qr_size": 200,
|
||||
"skew": 1,
|
||||
"type": "totp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete TOTP MFA Method
|
||||
|
||||
This endpoint deletes a TOTP MFA method.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :----------------------------- | :----------------------- |
|
||||
| `DELETE` | `/sys/mfa/method/totp/:name` | `204 (empty body)` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_totp
|
||||
|
||||
```
|
||||
|
||||
## 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 name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------------------ | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/totp/:name/generate` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_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 | Produces |
|
||||
| :------- | :------------------------------------------- | :----------------------- |
|
||||
| `POST` | `/sys/mfa/method/totp/:name/admin-generate` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
- `entity_id` `(string: <required>)` - Entity ID on which the generated secret
|
||||
needs to get stored.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"entity_id":"4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_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.
|
||||
|
||||
Note that in order to overwrite a secret on the entity, it is required to
|
||||
explicitly delete the secret first. 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 | Produces |
|
||||
| :------- | :-------------------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/:name/admin-destroy` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `entity_id` `(string: <required>)` - Entity ID from which the MFA secret
|
||||
should be removed.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"entity_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
https://vault.rocks/v1/sys/mfa/method/totp/my_totp/admin-destroy
|
||||
```
|
|
@ -10,232 +10,10 @@ description: |-
|
|||
|
||||
~> **Enterprise Only** – These endpoints require Vault Enterprise.
|
||||
|
||||
## Configure MFA Method
|
||||
## Supported MFA types.
|
||||
|
||||
This endpoint defines a specific `type` of MFA method. Once set, the `type` of the MFA
|
||||
method is immutable.
|
||||
- [TOTP](/api/system/mfa-totp.html)
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------ | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/:name` | `204 (empty body)` |
|
||||
- [Okta](/api/system/mfa-okta.html)
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `type` `(string: <required>)` - Type of the MFA method. Currently it only
|
||||
supports `totp`.
|
||||
|
||||
#### Type `totp` Parameters
|
||||
|
||||
- `totp_issuer` (string: <required>) - The name of the key's issuing organization.
|
||||
|
||||
- `totp_period` (int or duration format string: 30) - The length of time used to generate a counter for the TOTP token calculation.
|
||||
|
||||
- `totp_key_size` `(int: 20)` – Specifies the size in bytes of the generated key.
|
||||
|
||||
- `totp_qr_size` `(int: 200)` - The pixel size of the generated square QR code.
|
||||
|
||||
- `totp_algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512".
|
||||
|
||||
- `totp_digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8.
|
||||
|
||||
- `totp_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
|
||||
{
|
||||
"type": "totp",
|
||||
"issuer": "vault"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/mfa/method/my_totp
|
||||
```
|
||||
|
||||
## Read MFA Method
|
||||
|
||||
This endpoint queries the MFA configuration for a given name.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------ | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/:name` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/my_totp
|
||||
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"algorithm": "SHA1",
|
||||
"digits": 6,
|
||||
"id": "2dad2a3e-8ef0-fcf5-8b6f-d8ca14cabac4",
|
||||
"issuer": "vault",
|
||||
"key_size": 20,
|
||||
"name": "my_totp",
|
||||
"period": 30,
|
||||
"qr_size": 200,
|
||||
"skew": 1,
|
||||
"type": "totp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete MFA Method
|
||||
|
||||
This endpoint deletes a MFA configuration.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------ | :----------------------- |
|
||||
| `DELETE` | `/sys/mfa/method/:name` | `204 (empty body)` |
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request DELETE \
|
||||
https://vault.rocks/v1/sys/mfa/method/my_totp
|
||||
|
||||
```
|
||||
|
||||
## Generate MFA Secret
|
||||
|
||||
This endpoint generates an MFA secret in the entity of the calling token, if it
|
||||
doesn't exist already.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :------------------------------- | :----------------------- |
|
||||
| `GET` | `/sys/mfa/method/:name/generate` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request GET \
|
||||
https://vault.rocks/v1/sys/mfa/method/my_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 MFA Secret
|
||||
|
||||
This endpoint is can be used to generate an MFA secret on a given entity ID as
|
||||
opposed to entity of the calling token.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :-------------------------------------- | :----------------------- |
|
||||
| `POST` | `/sys/mfa/method/:name/admin-generate` | `200 application/json` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` - Name of the MFA method.
|
||||
|
||||
- `entity_id` `(string: <required>)` - Entity ID on which the generated secret
|
||||
needs to get stored.
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"entity_id":"4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
https://vault.rocks/v1/sys/mfa/method/my_totp/admin-generate
|
||||
```
|
||||
|
||||
### Sample Response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGZElEQVR4nOyd7W4jNwxFkyLv/8pbpMAAHnUo8pJyc1Oc82OB2KOP9QVFSyTlrz9/PsCIv356AnDn6/ufz89e48i6ov6u59f319ezfqtWnf2/snHX19XnVL7bYyFmIIgZCGLG5/e61V2b37WWXkRr9+lxonEvqv1XfeHK6/NYiBkIYgaCmPH19GK2j4ieX9/P9h0R2T6l+pzqYzKfmM0zQvk8sRAzEMQMBDHj0YdMqa6Z1TOvyDdF/VTPnqLnVzIfePLEHAsxA0HMQBAz3uJDqvuVbO1Vv/934yzReNV4ykmwEDMQxAwEMePRh5xeG6fxjNXnVM+Y1HHVM7Tq56R8nliIGQhiBoKYcfMhp2LT6hp7UY2hV8dTY/KZT1N9SufzxELMQBAzEMSMf3zI6X2HembUXbuz8dT9g+qLIiafJxZiBoKYgSBm3OpDunlMartTubrdeEUWI1dzAqa5wK9gIWYgiBkIYsaReIi6P1jbqd/7qznDqm9SfcKJs6sVLMQMBDEDQcz43K3z3fqLaf336fiFymQf8dRe8aVYiBkIYgaCmHHzIdW8pGo8QT1rOuULTvkc9a6TqD+lTgULMQNBzEAQMx7jIRdqjV7ULvpbrReJxl/nodYodseLxu/GWz6wED8QxAwEMeN2X9ZK9/4neRLDNfrUc919yPp8t/8PLMQPBDEDQcyQ6tTVO0JWqvGT6PWu75jub6L+T/kg4iHGIIgZCGLGKB5yKn5SpVuDWKXrI0/4jgssxAwEMQNBzNieZWV0v/erZ0Knxp3OYxoXqoyPhZiBIGYgiBmPub1q7m7G6fiB2n+3niSbZwT7kP8RCGIGgpjxeF9W5iPU8/+ofUY1r6q6ZkfzmtbJV2skozw04iHGIIgZCGKGlJeVvZ61V+MX07OiqJ9oftE41fGm9TD4EEMQxAwEMaN010lW1zGNoVfX+OrZl/rcfx0P2c0XCzEDQcxAEDMe87K68YBubH7tdxonmcb0q+2qZ2DK/gkLMQNBzEAQM2516lXUs6GIbA3v+qruPinrX/Ud0Xx288JCzEAQMxDEjG2NYXf/odztsXuuEoOu9BO93933RONm86n0h4WYgSBmIIgZt9+gqtaDq7m3K2rObnc+UT/Z36f2MZ28MCzEDAQxA0HMaJ1lTevBo/5OxRsysv1O9Fx1nO4Z3QcW4geCmIEgZki/H1Klu+Z369PVeVXHexfEQ34RCGIGgpjxWGN40c1VXdtXaxW79SLTOvqonVpDqdavkNv7C0AQMxDEjNK9vdP4gFq3ntV1Z+NEf099ZEZ1vrv+sBAzEMQMBDFjW2PYjT9U4xqqT1D7/ak4j5rn9QoWYgaCmIEgZpTu7e2u5Vk/4aQO3XFSHUc9s1rnNfVdr/1hIWYgiBkIYsZtH6LGA9Z20d8Z3fuq1HyqUznC1fZVX0c8xBgEMQNBzNje2xvxrlzYan1K1H82fjXOUfU12XzW5yufBxZiBoKYgSBmSL+FezE9s1lR9yHq2VvUT7fefOpjd58fFmIGgpiBIGZId52sr6u5u9M7RtTn1Hmr8ZzqnSvK2R4WYgaCmIEgZmzjIdHr3Rzfi278I3pdvStFrWVUfU52d8quPRZiBoKYgSBmbOvU//Xwobr1U7FpNV8qatetm4+onvU9jYuFmIEgZiCIGbf7srLv1d01vLsWqzmzapymeyaWfQ5qXtsrWIgZCGIGgphR+g2q9f0V9Y6SartsXtP8qOmZWDTe5AwMCzEDQcxAEDMeY+rVfUj0fLddN9Y+3feodfPd+pnKvLAQMxDEDAQxY1unPo11q+2i8adxCXV+an/qfHbzwELMQBAzEMQMKaYediL6FDVmruaBTWsU1bMwdT67/zcWYgaCmIEgZrR+g+piPata18Tu9/Zurq5aTxLNV833qs6nMg8sxAwEMQNBzHisD8lQ6y3W/qt3kpyuS8/ez3xiNL/qfMjL+oUgiBkIYkYppn7R9THd56s5tBGn60myfcSJ3GMsxAwEMQNBzGjdlxXRja1068mj9tla3c3DysaLxon+fgILMQNBzEAQM476kG5c5aJ7BnS6bqX6+jS/jLysXwCCmIEgZmx/x7DK6btCurF31WdMawPfkXOMhZiBIGYgiBmPvx+iUo2RV/vp3llSpZuXpfqgbNwnsBAzEMQMBDHjSH0InAMLMePvAAAA//8x2VnbmmL6HQAAAABJRU5ErkJggg==",
|
||||
"url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Administratively Destroy MFA Secret
|
||||
|
||||
This endpoint deletes an MFA secret from the given entity ID. This needs to be
|
||||
called if an existing secret in an entity needs to be overwritten by calling
|
||||
`generate` or `admin-generate` APIs.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| :------- | :-------------------------------------- | :--------------------- |
|
||||
| `POST` | `/sys/mfa/method/:name/admin-destroy` | `204 (empty body)` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `name` `(string: <required>)` – Name of the MFA method.
|
||||
|
||||
- `entity_id` `(string: <required>)` - Entity ID from which the MFA secret
|
||||
should be removed.
|
||||
|
||||
|
||||
### Sample Payload
|
||||
|
||||
```json
|
||||
{
|
||||
"entity_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample Request
|
||||
|
||||
```
|
||||
$ curl \
|
||||
--header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
https://vault.rocks/v1/sys/mfa/method/my_totp/admin-destroy
|
||||
```
|
||||
- [Duo](/api/system/mfa-duo.html)
|
||||
|
|
|
@ -175,6 +175,17 @@
|
|||
</li>
|
||||
<li<%= sidebar_current("docs-http-system-mfa") %>>
|
||||
<a href="/api/system/mfa.html"><tt>/sys/mfa</tt></a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-http-system-mfa-totp") %>>
|
||||
<a href="/api/system/mfa-totp.html"><tt>/sys/mfa/method/totp</tt></a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-system-mfa-okta") %>>
|
||||
<a href="/api/system/mfa-okta.html"><tt>/sys/mfa/method/okta</tt></a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-system-mfa-duo") %>>
|
||||
<a href="/api/system/mfa-duo.html"><tt>/sys/mfa/method/duo</tt></a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-http-system-mounts") %>>
|
||||
<a href="/api/system/mounts.html"><tt>/sys/mounts</tt></a>
|
||||
|
|
Loading…
Reference in a new issue