84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "TOTP Secret Backend"
|
|
sidebar_current: "docs-secrets-totp"
|
|
description: |-
|
|
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.
|
|
|
|
```text
|
|
$ 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:
|
|
|
|
```text
|
|
$ 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:
|
|
|
|
```text
|
|
$ 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.
|
|
|
|
```text
|
|
$ 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.
|
|
|
|
```text
|
|
$ 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](/api/secret/totp/index.html) for more
|
|
details.
|