docs: MFA usage details (#3133)

This commit is contained in:
Vishal Nayak
2017-08-08 23:48:31 -04:00
committed by GitHub
parent 27b2764c28
commit d2b3f42936
5 changed files with 521 additions and 0 deletions

View File

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

View File

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

View File

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

View File

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

View File

@@ -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>