docs: MFA usage details (#3133)

hashicorp · Aug 9, 2017 · d2b3f42 · d2b3f42
1 parent 27b2764
commit d2b3f42
Show file tree

Hide file tree

Showing 5 changed files with 521 additions and 0 deletions.
diff --git a/website/source/docs/vault-enterprise/mfa/index.html.md b/website/source/docs/vault-enterprise/mfa/index.html.md
@@ -0,0 +1,71 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise MFA Support"
+sidebar_current: "docs-vault-enterprise-mfa"
+description: |-
+  Vault Enterprise has support for Multi-factor Authentication (MFA), using different authentication types.
+
+---
+
+# Vault Enterprise MFA Support
+
+Vault Enterprise has support for Multi-factor Authentication (MFA), using
+different authentication types. MFA is built on top of the Identity system of
+Vault.
+
+## MFA Types
+
+MFA in Vault can be of the following types.
+
+- `Time-based One-time Password (TOTP)` - If configured and enabled on a path,
+  this would require a TOTP passcode along with Vault token, to be presented
+  while invoking the API request. The passcode will be validated against the
+  TOTP key present in the identity of the caller in Vault.
+
+- `Okta` - If Okta push is configured and enabled on a path, then the enrolled
+  device of the user will get a push notification to approve or deny the access
+  to the API. The Okta username will be derived from the caller identity's
+  persona.
+
+- `Duo` - If Duo push is configured and enabled on a path, then the enrolled
+  device of the user will get a push notification to approve or deny the access
+  to the API. The Duo username will be derived from the caller identity's
+  persona.
+
+## Configuring MFA Methods
+
+MFA methods are globally managed within the `System Backend` using the HTTP API.
+Please see [MFA API](/api/system/mfa.html) for details on how to configure an MFA
+method.
+
+## MFA Methods In Policies
+
+MFA requirements on paths are specified as `mfa_methods` along with other ACL
+parameters.
+
+### Sample Policy
+
+```
+path "secret/foo" {
+    capabilities = ["read"]
+    mfa_methods = ["dev_team_duo", "sales_team_totp"]
+}
+```
+
+The above policy grants `read` access to `secret/foo` only after *both* the MFA
+methods `dev_team_duo` and `sales_team_totp` are validated.
+
+## Supplying MFA Credentials
+
+MFA credentials are retrieved from the `X-Vault-MFA` HTTP header. The format of
+the header is `mfa_method_name[:key[=value]]`. The items in the `[]` are
+optional.
+
+### Sample Request
+
+```
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --header "X-Vault-MFA:my_totp:695452" \
+    https://vault.rocks/v1/secret/foo
+```
diff --git a/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md b/website/source/docs/vault-enterprise/mfa/mfa-duo.html.md
@@ -0,0 +1,141 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise Duo MFA"
+sidebar_current: "docs-vault-enterprise-mfa-duo"
+description: |-
+  Vault Enterprise supports Duo MFA type.
+---
+
+# MFA Duo
+
+This page demonstrates the Duo MFA on ACL'd paths of Vault.
+
+## Steps
+
+### Enable Auth Backend
+
+```
+vault auth-enable userpass
+```
+
+### Fetch Mount Accessor
+
+```
+vault auth -methods
+```
+
+```
+Path       Type      Accessor                Default TTL  Max TTL  Replication Behavior  Description
+...
+userpass/  userpass  auth_userpass_54b8e339  system       system   replicated
+```
+
+
+### Configure Duo MFA method
+
+```
+vault write sys/mfa/method/duo/my_duo mount_accessor=auth_userpass_54b8e339 integration_key=BIACEUEAXI20BNWTEYXT secret_key=HIGTHtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz api_hostname=api-2b5c39f5.duosecurity.com
+```
+
+### Create Policy
+
+Create a policy that gives access to secret through the MFA method created
+above.
+
+#### Sample Payload
+
+```hcl
+path "secret/foo" {
+    capabilities = ["read"]
+    mfa_methods = ["my_duo"]
+}
+```
+
+```
+vault policy-write duo-policy payload.hcl
+```
+
+### Create User
+
+MFA works only for tokens that have identity information on them. Tokens
+created by logging in using authentication backends will have the associated
+identity information. Let's create a user in the `userpass` backend and
+authenticate against it.
+
+
+```
+vault write auth/userpass/users/testuser password=testpassword policies=duo-policy
+```
+
+### Create Login Token
+
+```
+vault write auth/userpass/login/testuser password=testpassword
+```
+
+```
+Key                     Value
+---                     -----
+token                   70f97438-e174-c03c-40fe-6bcdc1028d6c
+token_accessor          a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
+token_duration          768h0m0s
+token_renewable         true
+token_policies          [default duo-policy]
+token_meta_username     "testuser"
+```
+
+Note that the CLI is not authenticated with the newly created token yet, we did
+not call `vault auth`, instead we used the login API to simply return a token.
+
+### Fetch Entity ID From Token
+
+Caller identity is represented by the `entity_id` property of the token.
+
+```
+vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
+```
+
+```
+Key                     Value
+---                     -----
+accessor                a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
+creation_time           1502245243
+creation_ttl            2764800
+display_name            userpass-testuser
+entity_id               307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
+expire_time             2017-09-09T22:20:43.448543132-04:00
+explicit_max_ttl        0
+id                      70f97438-e174-c03c-40fe-6bcdc1028d6c
+issue_time              2017-08-08T22:20:43.448543003-04:00
+meta                    map[username:testuser]
+num_uses                0
+orphan                  true
+path                    auth/userpass/login/testuser
+policies                [default duo-policy]
+renewable               true
+ttl                     2764623
+```
+
+### Login
+
+Authenticate the CLI to use the newly created token.
+
+```
+vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
+```
+
+### Read Secret
+
+Reading the secret will trigger a Duo push. This will be a blocking call until
+the push notification is either approved or declined.
+
+```
+vault read secret/foo
+```
+
+```
+Key                     Value
+---                     -----
+refresh_interval        768h0m0s
+data                    which can only be read after MFA validation
+```
diff --git a/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md b/website/source/docs/vault-enterprise/mfa/mfa-okta.html.md
@@ -0,0 +1,141 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise Okta MFA"
+sidebar_current: "docs-vault-enterprise-mfa-okta"
+description: |-
+  Vault Enterprise supports Okta MFA type.
+---
+
+# MFA Okta
+
+This page demonstrates the Okta MFA on ACL'd paths of Vault.
+
+## Steps
+
+### Enable Auth Backend
+
+```
+vault auth-enable userpass
+```
+
+### Fetch Mount Accessor
+
+```
+vault auth -methods
+```
+
+```
+Path       Type      Accessor                Default TTL  Max TTL  Replication Behavior  Description
+...
+userpass/  userpass  auth_userpass_54b8e339  system       system   replicated
+```
+
+
+### Configure Okta MFA method
+
+```
+vault write sys/mfa/method/okta/okta mount_accessor=auth_userpass_54b8e339 org_name="dev-262775" api_token="0071u8PrReNkzmATGJAP2oDyIXwwveqx9vIOEyCZDC"
+```
+
+### Create Policy
+
+Create a policy that gives access to secret through the MFA method created
+above.
+
+#### Sample Payload
+
+```hcl
+path "secret/foo" {
+    capabilities = ["read"]
+    mfa_methods = ["my_okta"]
+}
+```
+
+```
+vault policy-write okta-policy payload.hcl
+```
+
+### Create User
+
+MFA works only for tokens that have identity information on them. Tokens
+created by logging in using authentication backends will have the associated
+identity information. Let's create a user in the `userpass` backend and
+authenticate against it.
+
+
+```
+vault write auth/userpass/users/testuser password=testpassword policies=okta-policy
+```
+
+### Create Login Token
+
+```
+vault write auth/userpass/login/testuser password=testpassword
+```
+
+```
+Key                     Value
+---                     -----
+token                   70f97438-e174-c03c-40fe-6bcdc1028d6c
+token_accessor          a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
+token_duration          768h0m0s
+token_renewable         true
+token_policies          [default okta-policy]
+token_meta_username     "testuser"
+```
+
+Note that the CLI is not authenticated with the newly created token yet, we did
+not call `vault auth`, instead we used the login API to simply return a token.
+
+### Fetch Entity ID From Token
+
+Caller identity is represented by the `entity_id` property of the token.
+
+```
+vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
+```
+
+```
+Key                     Value
+---                     -----
+accessor                a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
+creation_time           1502245243
+creation_ttl            2764800
+display_name            userpass-testuser
+entity_id               307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
+expire_time             2017-09-09T22:20:43.448543132-04:00
+explicit_max_ttl        0
+id                      70f97438-e174-c03c-40fe-6bcdc1028d6c
+issue_time              2017-08-08T22:20:43.448543003-04:00
+meta                    map[username:testuser]
+num_uses                0
+orphan                  true
+path                    auth/userpass/login/testuser
+policies                [default okta-policy]
+renewable               true
+ttl                     2764623
+```
+
+### Login
+
+Authenticate the CLI to use the newly created token.
+
+```
+vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
+```
+
+### Read Secret
+
+Reading the secret will trigger an Okta push. This will be a blocking call until
+the push notification is either approved or declined.
+
+```
+vault read secret/foo
+```
+
+```
+Key                     Value
+---                     -----
+refresh_interval        768h0m0s
+data                    which can only be read after MFA validation
+```