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.

Note

The token auth method typically should not be specified in any MFA Rules. The token auth method will include all previous auth methods for the original auth request and will match the appropriate ruleset. This is intentional, as the token method is used for rescoping/changing active projects.

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 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: Time-based One-time Password (TOTP)