Multi-Factor Authentication

Configuring MFA

MFA is configured on a per user basis via the user options multi_factor_auth_rules and
multi_factor_auth_enabled. Until these are set the
user can authenticate with any one of the enabled auth methods.

MFA rules

The MFA rules allow an admin to force a user to use specific forms of
authentication or combinations of forms of authentication to get a
token.

The rules are specified as follows via the user option multi_factor_auth_rules:

[["password", "totp"], ["password", "custom-auth-method"]]

They are a list of lists. The elements of the sub-lists must be
strings and are intended to mirror the required authentication method
names (e.g. password, totp, etc) as defined in
the keystone.conf file in the [auth] methods
option. Each list of methods specifies a rule.

If the auth methods provided by a user match (or exceed) the auth
methods in the list, that rule is used. The first rule found (rules will
not be processed in a specific order) that matches will be used. If a
user has the ruleset defined as [["password", "totp"]] the
user must provide both password and totp auth methods (and both methods
must succeed) to receive a token. However, if a user has a ruleset
defined as [["password"], ["password", "totp"]] the user
may use the password method on it’s own but would be
required to use both password and totp if
totp is specified at all.

Any auth methods that are not defined in keystone.conf
in the [auth] methods option are ignored when the rules are
processed. Empty rules are not allowed. If a rule is empty due to
no-valid auth methods existing within it, the rule is discarded at
authentication time. If there are no rules or no valid rules for the
user, authentication occurs in the default manner: any single configured
auth method is sufficient to receive a token.

Enabling MFA

Before the MFA rules take effect on a user, MFA has to be enabled for
that user via the user option multi_factor_auth_enabled. By default this is unset,
and the rules will not take effect until configured.

In the case a user should be exempt from MFA Rules, regardless if
they are set, the User-Option may be set to False.

Using MFA

See multi_factor_authentication_user_guide in the user
guide for some examples.

Supported
multi-factor authentication methods

TOTP is the only suggested second factor along with password for now,
but there are plans to include more in future.

TOTP

This is a simple 6 digit passcode generated by both the server and
client from a known shared secret.

This used in a multi-step fashion is the most common 2-factor method
used these days.

See: auth_totp