89 lines
3.2 KiB
ReStructuredText
89 lines
3.2 KiB
ReStructuredText
.. _multi_factor_authentication:
|
|
|
|
===========================
|
|
Multi-Factor Authentication
|
|
===========================
|
|
|
|
Configuring MFA
|
|
===============
|
|
|
|
MFA is configured on a per user basis via the user options
|
|
:ref:`multi_factor_auth_rules` and :ref:`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
|
|
:ref:`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 :ref:`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 :ref:`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: :ref:`auth_totp`
|