TOTP MFA

This page demonstrates the TOTP MFA on ACL'd paths of Vault.

Configuration

1. Enable the appropriate auth method:

   $ vault auth enable userpass

2. Fetch the mount accessor for the enabled auth method:

   $ vault auth list -detailed

   The response will look like:

   Path         Type        Accessor                  Plugin    Default TTL    Max TTL    Replication    Description----         ----        --------                  ------    -----------    -------    -----------    -----------token/       token       auth_token_289703e9       n/a       system         system     replicated     token based credentialsuserpass/    userpass    auth_userpass_54b8e339    n/a       system         system     replicated     n/a

3. Configure TOTP MFA:

   Note: Consider the algorithms supported by your authenticator. For example, Google Authenticator for Android supports only SHA1 as the value of algorithm.

   $ vault write sys/mfa/method/totp/my_totp \    issuer=Vault \    period=30 \    key_size=30 \    algorithm=SHA256 \    digits=6

4. Create a policy that gives access to secret through the MFA method created above:

   $ vault policy write totp-policy -<<EOFpath "secret/foo" {  capabilities = ["read"]  mfa_methods  = ["my_totp"]}EOF

5. Create a user. MFA works only for tokens that have identity information on them. Tokens created by logging in using auth methods will have the associated identity information. Create a user in the userpass auth method and authenticate against it:

   $ vault write auth/userpass/users/testuser \    password=testpassword \    policies=totp-policy

6. Create a login token:

   $ vault write auth/userpass/login/testuser \    password=testpasswordKey                    Value---                    -----token                  70f97438-e174-c03c-40fe-6bcdc1028d6ctoken_accessor         a91d97f4-1c7d-6af3-e4bf-971f74f9fab9token_duration         768htoken_renewable        truetoken_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 login, instead we used the login API to simply return a token.

7. Fetch the entity ID from the token. The caller identity is represented by the entity_id property of the token:

   $ vault token lookup 70f97438-e174-c03c-40fe-6bcdc1028d6cKey                 Value---                 -----accessor            a91d97f4-1c7d-6af3-e4bf-971f74f9fab9creation_time       1502245243creation_ttl        2764800display_name        userpass-testuserentity_id           307d6c16-6f5c-4ae7-46a9-2d153ffcbc63expire_time         2017-09-09T22:20:43.448543132-04:00explicit_max_ttl    0id                  70f97438-e174-c03c-40fe-6bcdc1028d6cissue_time          2017-08-08T22:20:43.448543003-04:00meta                map[username:testuser]num_uses            0orphan              truepath                auth/userpass/login/testuserpolicies            [default totp-policy]renewable           truettl                 2764623

8. Generate TOTP method attached to the entity. 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-2d153ffcbc63Key        Value---        -----barcode    iVBORw0KGgoAAAANSUhEUgAAAM...url        otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algo...

   Either the base64 encoded png barcode or the url should be given to the end user. This barcode/url can be loaded into Google Authenticator or a similar TOTP tool to generate codes.

9. Login as the user:

   $ vault login 70f97438-e174-c03c-40fe-6bcdc1028d6c

10. Read the secret, specifying the mfa flag:

    $ vault read -mfa my_totp:146378 secret/data/fooKey                 Value---                 -----refresh_interval    768hdata                which can only be read after MFA validation