docs: MFA usage details (#3133)

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
+```

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
+```

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
+```

website/source/docs/vault-enterprise/mfa/mfa-totp.html.md

@@ -0,0 +1,154 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise TOTP MFA"
+sidebar_current: "docs-vault-enterprise-mfa-totp"
+description: |-
+  Vault Enterprise supports TOTP MFA type.
+---
+
+# MFA TOTP
+
+This page demonstrates the TOTP MFA on ACL'd paths of Vault.
+
+## Steps
+
+### Configure TOTP MFA method
+
+```
+vault write sys/mfa/method/totp/my_totp issuer=Vault period=30 key_size=30 algorithm=SHA256 digits=6
+```
+
+### Create Secret
+
+Create a secret to be accessed after validating MFA.
+
+```
+vault write secret/foo data="which can only be read after MFA validation"
+```
+
+### 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_totp"]
+}
+```
+
+```
+vault policy-write totp-policy payload.hcl
+```
+
+### Enable Auth Backend
+
+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 auth-enable userpass
+```
+
+### Create User
+
+```
+vault write auth/userpass/users/testuser password=testpassword policies=totp-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 totp-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 totp-policy]
+renewable               true
+ttl                     2764623
+```
+
+### Generate TOTP Method Secret on Entity
+
+Let's generate a TOTP key using the `my_totp` configuration and store it in the
+entity of the user. A barcode and a URL for the secret key will be returned by
+the API. This should be distributed to the intended user to be able to generate
+TOTP passcode.
+
+```
+vault write sys/mfa/method/totp/my_totp/admin-generate entity_id=307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
+```
+
+```
+Key     Value
+---     -----
+barcode iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAG50lEQVR4nOydwW4sOwhEX57y/7+cu3AWvkKgA/To1ozqrKJut9tJCYRxZeb75+c/I8T//3oB5m8siBgWRAwLIoYFEcOCiGFBxLAgYlgQMSyIGBZEDAsihgURw4KIYUHEsCBiWBAxLIgYFkSMbzrw64uOzE7pzwzn7j3bPT6+5R6f/RxHkvXEN8aR/G4Ndy44QsSwIGLglHXg4R+vxIRTj7nv3uPjz2dMHEnmzxJd9tvF+bt/kxpHiBgWRIxmyjqQSiarT2KyimnnHpmlwTrVZPNkCTNLO3UFmL0xPstxhIhhQcQYpSxOlsrqWiWmLz7/fb1OU/UM2cg6xe1xhIhhQcR4ccriySGOv5/qbuW6Xal6ntmzMxwhYlgQMUYpqxu2WX1CGuZ1uuCdKzJnPbLmqVTmCBHDgojRTFndZjI576t/zuaJq6qvb+asjwO6f5MaR4gYFkQMnLL2VUSdQDbv6iarewyfJ455xSbRESKGBRHji4YdOac71GeCpN39lG1gNg8/T+z20wiOEDEsiBiLKqubmriJlCST2lYa5yEJpLtm0pzvnjA6QsSwIGLgKut3eNN5fsP7Rd1OV7fHVf922Zp5F2uzYXSEiGFBxGimrN+HQNIgW6pu+JPElT3Lx8SR3Q0m/ztEHCFiWBAxFieG9UYsu3Lg1Qv3w8eZs/l5qqxNrfVG0r2sj8CCiPFQlTWbIVK7p2aeK1Iv8Tb7xqpBcISIYUHEWPeyajtofZ374bm5ND5bj9xs67rbYYIjRAwLIsajJodZbyrerVPBrGdVj490Dxrsfv9QLIgYD/3Dzt3zOXf5pmxmP7ivkxqvTmu8K5VdeSqJOULEsCBirN3vs39gqf8FpttCv6/wjR45i8yu1PB0HXGEiGFBxBh9KunMTllvr2YeJ94Gr9dWnyeS3l135RmOEDEsiBjrE8OujZOnpu4pXn2XN9K5wbWeh/wWEUeIGBZEjPUnOZCqI0sv3TNH4q3KKkBSKc3OMWe2igxHiBgWRIzFZ79vNoPdvlCc+b7LDQzkLeS0kZ8husp6cyyIGCNf1qF7Bkca45FuH4nXSGQGYiIla+Y4QsSwIGI89A07+x5ONwl00+M9snu+Sda832weHCFiWBAxFp/9noVnfYVXX+Sckb8ljuym0/qNsxPPiCNEDAsixqj9nnmi4sj7bubFImeF0apan0gSm2iE15C8rnOV9eZYEDFGG8NZeHKHVbcy4YmUNM+5PaNOZfZlfQQWRIxHv66i63rKnuUpqL5O1lmn33p8XR+6/f4RWBAxFr2srOOUQaqUbkeI+8FqsiRDElp211XWR2BBxHjI5FCfGG7MD9n82dq4a31miyWzbQyljhAxLIgYzQ+fOczO4zYGhpmJoruNJW/hqW+GI0QMCyLGo5/kwM8N46Yya1zXdgKSuGbngN2uVNdYm+EIEcOCiNH8JAe+NTtkqak+lSO2UrJaMid5C084+4rLESKGBRFj1H7P6ocsLZANXV071U1+sp0kllRSKc16WRxHiBgWRIxFL4t0nLJ5eODXz97w2owkE76dnP0dMhwhYlgQMZq9rCw89xs6cuaYVXR1pVePzNZA7Kb1G7Pfq8YRIoYFEePRr149kCqI2wn2bNIpr6BIBUhwhIhhQcQYfZByvE6c6rwimq2EW1K7Jopun6q7Cb1xhIhhQcRYbAwjmzM+bjrNrtdbs2wG7mOfOdN8YvjmWBAxHvq6ivtnshHb1DmROrl1O1Fxzu74WfV4cISIYUHEWPSybrJkNXOJZ/Pw7V69qnqGunlet9NnaerGESKGBRFjZHK4Icf6z9oh9p4ovgmNT83GuMp6WyyIGItvi44dpJkfqdug5r4sbjHla4hbzmzM/UaOI0QMCyLGo19XEcfcdE/f+LYxe6p7tsjrKO7L6uIIEcOCiLH+UrBZt6qe+YZYI8j4OCa+nRhW47NPmUgPjhAxLIgYo/Y7mvgFziiSEMgWjxhB+TrJetzLelssiBhrK2kkWgtm1koe5qSyiuPju/j17L38boYjRAwLIsZD32N4yLxPmUuKnx5uzBL3mKyCmjXkiR+siyNEDAsixvrDZw5ZeNYbt5n/ql5JPb5eZ92VyhJyNg9PyDeOEDEsiBiLr6sg1AFbVzsZ5Aigm1R5lcWNpl3zxsERIoYFEePFKYtUX1niyu7e12eWA1LpRXina5asDo4QMSyIGAsr6WzM7FmyYdxvV8kxAW/1u/3+EVgQMR796tV6JN8uzSyg3A5Rr4HP0DVCEBwhYlgQMV7myzIzHCFiWBAxLIgYFkQMCyKGBRHDgohhQcSwIGJYEDEsiBgWRAwLIoYFEcOCiGFBxLAgYlgQMSyIGBZEjD8BAAD//xDzM7XcohEsAAAAAElFTkSuQmCC
+url     otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algorithm=SHA256&digits=6&issuer=Vault&period=30&secret=AQESPQUPHWYIXV7FGOMBYT3A2N4LQKEIRNKTSRCWTKVEW66L
+```
+
+Note that Vault's [TOTP secret backend](/docs/secrets/totp/index.html) can be leveraged to create TOTP passcodes.
+
+### Login
+
+Authenticate the CLI to use the newly created token.
+
+```
+vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
+```
+
+### Read Secret
+
+Read the secret by supplying the TOTP passcode.
+
+```
+vault read -mfa my_totp:146378 secret/foo
+```
+
+```
+Key                     Value
+---                     -----
+refresh_interval        768h0m0s
+data                    which can only be read after MFA validation
+```

website/source/layouts/docs.erb

@@ -372,6 +372,20 @@
           <li<%= sidebar_current("docs-vault-enterprise-ui") %>>
             <a href="/docs/vault-enterprise/ui/index.html">UI (Web Interface)</a>
           </li>
+          <li <%= sidebar_current("docs-vault-enterprise-mfa")%> >
+            <a href="/docs/vault-enterprise/mfa/index.html">MFA</a>
+            <ul class="nav">
+              <li <%= sidebar_current("docs-vault-enterprise-mfa-totp")%>>
+                <a href="/docs/vault-enterprise/mfa/mfa-totp.html">TOTP MFA</a>
+              </li>
+              <li <%= sidebar_current("docs-vault-enterprise-mfa-okta")%>>
+                <a href="/docs/vault-enterprise/mfa/mfa-okta.html">Okta MFA</a>
+              </li>
+              <li <%= sidebar_current("docs-vault-enterprise-mfa-duo")%>>
+                <a href="/docs/vault-enterprise/mfa/mfa-duo.html">Duo MFA</a>
+              </li>
+            </ul>
+          </li>
         </ul>
       </li>
     </ul>