191 lines
4.6 KiB
ReStructuredText
191 lines
4.6 KiB
ReStructuredText
================
|
|
Resource Options
|
|
================
|
|
|
|
A resource option is an attribute that can be optionally set on an entity in
|
|
keystone. These options are used to control specific features or behaviors
|
|
within keystone. This allows flexibility on a per-resource basis as opposed to
|
|
settings a configuration file value that controls a behavior for all resources
|
|
in a deployment.
|
|
|
|
This flexibility can be useful for deployments is setting different
|
|
authentication requirements for users. For example, operators can use resource
|
|
options to set the number of failed authentication attempts on a per-user basis
|
|
as opposed to setting a global value that is applied to all users.
|
|
|
|
The purpose of this document is to formally document the supported resource
|
|
options used in keystone, their intended behavior, and how to use them.
|
|
|
|
User Options
|
|
============
|
|
|
|
The following options are available on user resources. If left undefined, they
|
|
are assumed to be false or disabled.
|
|
|
|
These can be set either in the initial user creation (``POST /v3/users``)
|
|
or by updating an existing user to include new options
|
|
(``PATCH /v3/users/{user_id}``):
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"ignore_lockout_failure_attempts": true
|
|
}
|
|
}
|
|
}
|
|
|
|
.. note::
|
|
|
|
User options of the ``Boolean`` type can be set to ``True``, ``False``, or
|
|
``None``; if the option is set to ``None``, it is removed from the user's
|
|
data structure.
|
|
|
|
.. _ignore_change_password_upon_first_use:
|
|
|
|
ignore_change_password_upon_first_use
|
|
-------------------------------------
|
|
|
|
Type: ``Boolean``
|
|
|
|
Control if a user should be forced to change their password immediately after
|
|
they log into keystone for the first time. This can be useful for deployments
|
|
that auto-generate passwords but want to ensure a user picks a new password
|
|
when they start using the deployment.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"ignore_change_password_upon_first_use": true
|
|
}
|
|
}
|
|
}
|
|
|
|
See the :ref:`security compliance documentation
|
|
<security_compliance>` for more details.
|
|
|
|
.. _ignore_password_expiry:
|
|
|
|
ignore_password_expiry
|
|
----------------------
|
|
|
|
Type: ``Boolean``
|
|
|
|
Opt into ignoring global password expiration settings defined in
|
|
``keystone.conf [security_compliance]`` on a per-user basis. Setting this
|
|
option to ``True`` will allow users to continue using passwords that may be
|
|
expired according to global configuration values.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"ignore_password_expiry": true
|
|
}
|
|
}
|
|
}
|
|
|
|
See the :ref:`security compliance documentation
|
|
<security_compliance>` for more details.
|
|
|
|
.. _ignore_lockout_failure_attempts:
|
|
|
|
ignore_lockout_failure_attempts
|
|
-------------------------------
|
|
|
|
Type: ``Boolean``
|
|
|
|
If ``True``, opt into ignoring the number of times a user has authenticated and
|
|
locking out the user as a result.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"ignore_lockout_failure_attempts": true
|
|
}
|
|
}
|
|
}
|
|
|
|
See the :ref:`security compliance documentation
|
|
<security_compliance>` for more details.
|
|
|
|
.. _lock_password:
|
|
|
|
lock_password
|
|
-------------
|
|
|
|
Type: ``Boolean``
|
|
|
|
If set to ``True``, this option disables the ability for users to change their
|
|
password through self-service APIs.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"lock_password": true
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
See the :ref:`security compliance documentation
|
|
<security_compliance>` for more details.
|
|
|
|
.. _multi_factor_auth_enabled:
|
|
|
|
multi_factor_auth_enabled
|
|
-------------------------
|
|
|
|
Type: ``Boolean``
|
|
|
|
Specify if a user has multi-factor authentication enabled on their account.
|
|
This will result in different behavior at authentication time and the user may
|
|
be presented with different authentication requirements based on multi-factor
|
|
configuration.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"multi_factor_auth_enabled": true
|
|
}
|
|
}
|
|
}
|
|
|
|
See :ref:`multi_factor_authentication` for further details.
|
|
|
|
.. _multi_factor_auth_rules:
|
|
|
|
multi_factor_auth_rules
|
|
-----------------------
|
|
|
|
Type: ``List of Lists of Strings``
|
|
|
|
Define a list of strings that represent the methods required for a user to
|
|
authenticate.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"user": {
|
|
"options": {
|
|
"multi_factor_auth_rules": [
|
|
["password", "totp"],
|
|
["password", "u2f"]
|
|
]
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
See :ref:`multi_factor_authentication` for further details.
|