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
hashicorp · Aug 9, 2017 · f2cf43b · f2cf43b
1 parent 6e6bd6e
commit f2cf43b
Show file tree

Hide file tree

Showing 5 changed files with 478 additions and 226 deletions.
diff --git a/website/source/api/system/mfa-duo.html.md b/website/source/api/system/mfa-duo.html.md
@@ -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
+
+```
diff --git a/website/source/api/system/mfa-okta.html.md b/website/source/api/system/mfa-okta.html.md
@@ -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
+
+```