.. _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`