Multi-Factor Authentication¶

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.

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)