open-vault/website/source/docs/auth/mfa.html.md

layout	page_title	sidebar_current	description
docs	Multi-Factor Authentication	docs-auth-mfa	Multi-factor authentication is supported for several authentication backends.

Multi-Factor Authentication

Several authentication backends support multi-factor authentication (MFA). Once enabled for a backend, users are required to provide additional verification, like a one-time passcode, before being authenticated.

Currently, the "ldap" and "userpass" backends support MFA.

Authentication

When authenticating, users still provide the same information as before, as well as MFA verification. Usually this is a passcode, but in other cases, like a Duo Push notification, no additional information is needed.

Via the CLI

$ vault auth -method=userpass username=user password=test passcode=111111
$ vault auth -method=userpass username=user password=test method=push  # (default)

Via the API

The endpoint for the login is the same as for the original backend. Additional MFA information should be sent in the POST body encoded as JSON.

$ curl $VAULT_ADDR/v1/auth/userpass/login/user \
    -d '{ "password": "test", "passcode": "111111" }'

The response is the same as for the original backend.

Configuration

To enable MFA for a supported backend, the MFA type must be set in mfa_config. For example:

$ vault write auth/userpass/mfa_config type=duo

This enables the Duo MFA type, which is currently the only MFA type supported.

Duo

The Duo MFA type is configured through two paths: duo/config and duo/access.

duo/access contains connection information for the Duo Auth API. For example:

$ vault write auth/userpass/duo/access \
    host=[host] \
    ikey=[integration key] \
    skey=[secret key]

duo/config is an optional path that contains general configuration information for Duo authentication. For example:

$ vault write auth/userpass/duo/config \
    user_agent="" \
    username_format="%s"

username_format is a format string that is formatted with the original backend's username as the first argument to produce the Duo username.