openstack/keystone
Code Issues Proposed changes

Add MFA Rules Release Note

Browse Source 
Add the release note for MFA Rules.

Change-Id: Id4aff9ba57d5b60110df1a7c752950d022ed58ec
bp: per-user-auth-plugin-reqs
This commit is contained in:
Morgan Fainberg 2017-01-31 09:36:29 -08:00
parent 113055774a
commit a64b474ef4
1 changed files with 64 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
releasenotes/notes/bp-per-user-auth-plugin-reqs-feb95fd907be4b40.yaml Normal file
View File

@ -0,0 +1,64 @@
---
features:
- |
[`blueprint per-user-auth-plugin-reqs <https://blueprints.launchpad.net/keystone/+spec/per-user-auth-plugin-reqs>`_]
Per-user Multi-Factor-Auth rules (MFA Rules) have been implemented. These
rules define which auth methods can be used (e.g. Password, TOTP) and
provides the ability to require multiple auth forms to successfully get
a token.
The MFA rules are set via the user create and update API
(``POST/PATCH /v3/users``) call; the options 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::
user["options"]["multi_factor_auth_rules"] = [["password", "totp"], ["password", "custom-auth-method"]]
The rules are specified as 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.
In the case a user should be exempt from MFA Rules, regardless if they are
set, the User-Option ``multi_factor_auth_enabled`` may be set to
``False`` for that user via the user create and update API
(``POST/PATCH /v3/users``) call. If this option is set to ``False`` the
MFA rules will be ignored for the user. Any other value except ``False``
will result in the MFA Rules being processed; the option can only be
a boolean (``True`` or ``False``) or "None" (which will result in the
default behavior (same as ``True``) but the option will no longer be shown
in the ``user["options"]`` dictionary.
To mark a user exempt from the MFA Rules::
user["options"]["multi_factor_auth_enabled"] = False
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.
SECURITY INFO: The MFA rules are only processed when authentication happens
through the V3 authentication APIs. If V2 Auth is enabled it is possible to
circumvent the MFA rules if the user can authenticate via V2 Auth API.
It is recommended to disable V2 authentication for full enforcement of
the MFA rules.