4c0e3c5d2f
* Initialized basic outline of TOTP backend using Postgresql backend as template * Updated TOTP backend.go's structure and help string * Updated TOTP path_roles.go's structure and help strings * Updated TOTP path_role_create.go's structure and help strings * Fixed typo in path_roles.go * Fixed errors in path_role_create.go and path_roles.go * Added TOTP secret backend information to cli commands * Fixed build errors in path_roles.go and path_role_create.go * Changed field values of period and digits from uint to int, added uint conversion of period when generating passwords * Initialized TOTP test file based on structure of postgresql test file * Added enforcement of input values * Added otp library to vendor folder * Added test steps and cleaned up errors * Modified read credential test step, not working yet * Use of vendored package not allowed - Test error * Removed vendor files for TOTP library * Revert "Removed vendor files for TOTP library" This reverts commit fcd030994bc1741dbf490f3995944e091b11da61. * Hopefully fixed vendor folder issue with TOTP Library * Added additional tests for TOTP backend * Cleaned up comments in TOTP backend_test.go * Added default values of period, algorithm and digits to field schema * Changed account_name and issuer fields to optional * Removed MD5 as a hash algorithm option * Implemented requested pull request changes * Added ability to validate TOTP codes * Added ability to have a key generated * Added skew, qr size and key size parameters * Reset vendor.json prior to merge * Readded otp and barcode libraries to vendor.json * Modified help strings for path_role_create.go * Fixed test issue in testAccStepReadRole * Cleaned up error formatting, variable names and path names. Also added some additional documentation * Moveed barcode and url output to key creation function and did some additional cleanup based on requested changes * Added ability to pass in TOTP urls * Added additional tests for TOTP server functions * Removed unused QRSize, URL and Generate members of keyEntry struct * Removed unnecessary urlstring variable from pathKeyCreate * Added website documentation for TOTP secret backend * Added errors if generate is true and url or key is passed, removed logger from backend, and revised parameter documentation. * Updated website documentation and added QR example * Added exported variable and ability to disable QR generation, cleaned up error reporting, changed default skew value, updated documentation and added additional tests * Updated API documentation to inlude to exported variable and qr size option * Cleaned up return statements in path_code, added error handling while validating codes and clarified documentation for generate parameters in path_keys
84 lines
2.7 KiB
Markdown
84 lines
2.7 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 `generic` 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.
|