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.
