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

---
layout: "docs"
page_title: "TOTP MFA - MFA Support - Vault Enterprise"
sidebar_title: "TOTP MFA"
sidebar_current: "docs-vault-enterprise-mfa-totp"
description: |-
  Vault Enterprise supports TOTP MFA type.
---

# TOTP MFA

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

## Configuration

1. Enable the appropriate auth method:

    ```text
    $ vault auth enable userpass
    ```

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

    ```text
    $ vault auth list -detailed
    ```

    The response will look like:

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

1. Configure TOTP MFA:

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

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

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

1. 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:


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

1. Create a login token:

    ```text
    $ 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"
    ```

    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.

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

    ```text
    $ 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
    ```

1. Generate TOTP method attached to the entity. This should be distributed to
the intended user to be able to generate TOTP passcode:

    ```text
    $ 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...
    ```

    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.

1. Login as the user:

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

1. Read the secret, specifying the mfa flag:

    ```text
    $ vault read -mfa my_totp:146378 secret/foo

    Key                 Value
    ---                 -----
    refresh_interval    768h
    data                which can only be read after MFA validation
    ```