»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
   

   $ vault auth enable userpass

   Copy

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

   $ vault auth list -detailed
   

   $ vault auth list -detailed

   Copy

   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 credentials
   userpass/    userpass    auth_userpass_54b8e339    n/a       system         system     replicated     n/a
   

   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

   Copy

3. Configure TOTP MFA:

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

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

   Copy

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

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

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

   Copy

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
   

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

   Copy

6. Create a 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         768h
   token_renewable        true
   token_policies         [default totp-policy]
   token_meta_username    "testuser"
   

   $ vault write auth/userpass/login/testuser \    password=testpassword
   Key                    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"

   Copy

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

   $ vault token lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
   Key                 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

   Copy

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-2d153ffcbc63
   
   Key        Value
   ---        -----
   barcode    iVBORw0KGgoAAAANSUhEUgAAAM...
   url        otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algo...
   

   $ vault write sys/mfa/method/totp/my_totp/admin-generate \    entity_id=307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
   Key        Value---        -----barcode    iVBORw0KGgoAAAANSUhEUgAAAM...url        otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algo...

   Copy

   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
   

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

   Copy

10. Read the secret, specifying the mfa flag:

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

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

    Copy