open-vault/website/source/docs/secrets/totp/index.html.md

layout	page_title	sidebar_current	description
docs	TOTP Secret Backend	docs-secrets-totp	The TOTP secret backend for Vault generates time-based one-time use passwords.

TOTP Secret Backend

Name: totp

The TOTP secret backend for Vault will allow Vault users to store their multi-factor authentication keys in Vault and use the API to retrieve time-based one-time use passwords on demand. The backend can also be used to generate a new key and validate passwords generated by that key.

This page will show a quick start for this backend. For detailed documentation on every path, use vault path-help after mounting the backend.

Quick Start

The first step to using the TOTP backend is to mount it. Unlike the kv backend, the totp backend is not mounted by default.

$ vault mount totp
Successfully mounted 'totp' at 'totp'!

The next step is to configure a key. For example, lets create a "test" key by passing in a TOTP key url:

$ vault write totp/keys/test \
    url="otpauth://totp/Vault:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Vault"
Success! Data written to: totp/keys/test

By writing to the keys/test path we are defining the test key.

To generate a new set of credentials, we simply read from that key using the code path:

$ vault read totp/code/test
Key           	Value
code            135031

Vault is now configured to create time-based one-time use passwords!

By reading from the code/test path, Vault has generated a new time-based one-time use password using the test key configuration.

Using ACLs, it is possible to restrict using the TOTP backend such that trusted operators can manage the key definitions, and both users and applications are restricted in the credentials they are allowed to read.

The TOTP backend can also be used to generate new keys and validate passwords generated using those keys.

In order to generate a new key, set the generate flag to true and pass in an issuer and account name.

$ vault write totp/keys/test \
    generate=true issuer=Vault account_name=test@gmail.com

A base64 encoded barcode and url will be returned upon generating a new key. These can be given to client applications that can generate passwords. You can validate those passwords by writing to the code/test path.

$ vault write totp/code/test \
    code=127388
Key           	Value
valid           true

If you get stuck at any time, simply run vault path-help totp or with a subpath for interactive help output.

API

The TOTP secret backend has a full HTTP API. Please see the TOTP secret backend API for more details.