Consolidate identity-domain-specific-config.rst
Consolidate from configuration.rst into identity-domain-specific-config.rst. Change-Id: Id989342e31be31a3c5cb946ff2177ffa5a8f47a8
This commit is contained in:
Suramya Shah
Colleen Murphy
parent
a32c596980
commit
ed6366813d
|
|
@ -49,6 +49,141 @@ Any domain-specific configuration options specified through the
|
|||
Identity v3 API will override domain-specific configuration files in the
|
||||
``/etc/keystone/domains`` directory.
|
||||
|
||||
Unlike the file-based method of specifying domain-specific configurations,
|
||||
options specified via the Identity API will become active without needing to
|
||||
restart the keystone server. For performance reasons, the current state of
|
||||
configuration options for a domain are cached in the keystone server, and in
|
||||
multi-process and multi-threaded keystone configurations, the new
|
||||
configuration options may not become active until the cache has timed out. The
|
||||
cache settings for domain config options can be adjusted in the general
|
||||
keystone configuration file (option ``cache_time`` in the ``domain_config``
|
||||
group).
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is important to notice that when using either of these methods of
|
||||
specifying domain-specific configuration options, the main keystone
|
||||
configuration file is still maintained. Only those options that relate
|
||||
to the Identity driver for users and groups (i.e. specifying whether the
|
||||
driver for this domain is SQL or LDAP, and, if LDAP, the options that
|
||||
define that connection) are supported in a domain-specific manner. Further,
|
||||
when using the configuration options via the Identity API, the driver
|
||||
option must be set to an LDAP driver (attempting to set it to an SQL driver
|
||||
will generate an error when it is subsequently used).
|
||||
|
||||
For existing installations that already use file-based domain-specific
|
||||
configurations who wish to migrate to the SQL-based approach, the
|
||||
``keystone-manage`` command can be used to upload all configuration files to
|
||||
the SQL database:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage domain_config_upload --all
|
||||
|
||||
Once uploaded, these domain-configuration options will be visible via the
|
||||
Identity API as well as applied to the domain-specific drivers. It is also
|
||||
possible to upload individual domain-specific configuration files by
|
||||
specifying the domain name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage domain_config_upload --domain-name DOMAINA
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is important to notice that by enabling either of the domain-specific
|
||||
configuration methods, the operations of listing all users and listing all
|
||||
groups are not supported, those calls will need either a domain filter to
|
||||
be specified or usage of a domain scoped token.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Keystone does not support moving the contents of a domain (i.e. "its" users
|
||||
and groups) from one backend to another, nor group membership across
|
||||
backend boundaries.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
When using the file-based domain-specific configuration method, to delete a
|
||||
domain that uses a domain specific backend, it's necessary to first disable
|
||||
it, remove its specific configuration file (i.e. its corresponding
|
||||
keystone.<domain_name>.conf) and then restart the Identity server. When
|
||||
managing configuration options via the Identity API, the domain can simply
|
||||
be disabled and deleted via the Identity API; since any domain-specific
|
||||
configuration options will automatically be removed.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Although keystone supports multiple LDAP backends via the above
|
||||
domain-specific configuration methods, it currently only supports one SQL
|
||||
backend. This could be either the default driver or a single
|
||||
domain-specific backend, perhaps for storing service users in a
|
||||
predominantly LDAP installation.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Keystone has deprecated the ``keystone-manage domain_config_upload``
|
||||
option. The keystone team recommends setting domain config options via the
|
||||
API instead.
|
||||
|
||||
Due to the need for user and group IDs to be unique across an OpenStack
|
||||
installation and for keystone to be able to deduce which domain and backend to
|
||||
use from just a user or group ID, it dynamically builds a persistent identity
|
||||
mapping table from a public ID to the actual domain, local ID (within that
|
||||
backend) and entity type. The public ID is automatically generated by keystone
|
||||
when it first encounters the entity. If the local ID of the entity is from a
|
||||
backend that does not guarantee to generate UUIDs, a hash algorithm will
|
||||
generate a public ID for that entity, which is what will be exposed by
|
||||
keystone.
|
||||
|
||||
The use of a hash will ensure that if the public ID needs to be regenerated
|
||||
then the same public ID will be created. This is useful if you are running
|
||||
multiple keystones and want to ensure the same ID would be generated whichever
|
||||
server you hit.
|
||||
|
||||
While keystone will dynamically maintain the identity mapping, including
|
||||
removing entries when entities are deleted via the keystone, for those entities
|
||||
in backends that are managed outside of keystone (e.g. a read-only LDAP),
|
||||
keystone will not know if entities have been deleted and hence will continue to
|
||||
carry stale identity mappings in its table. While benign, keystone provides an
|
||||
ability for operators to purge the mapping table of such stale entries using
|
||||
the keystone-manage command, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
|
||||
|
||||
A typical usage would be for an operator to obtain a list of those entries in
|
||||
an external backend that had been deleted out-of-band to keystone, and then
|
||||
call keystone-manage to purge those entries by specifying the domain and
|
||||
local-id. The type of the entity (i.e. user or group) may also be specified if
|
||||
this is needed to uniquely identify the mapping.
|
||||
|
||||
Since public IDs can be regenerated **with the correct generator
|
||||
implementation**, if the details of those entries that have been deleted are
|
||||
not available, then it is safe to simply bulk purge identity mappings
|
||||
periodically, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --domain-name DOMAINA
|
||||
|
||||
will purge all the mappings for DOMAINA. The entire mapping table can be purged
|
||||
with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --all
|
||||
|
||||
Generating public IDs in the first run may take a while, and most probably
|
||||
first API requests to fetch user list will fail by timeout. To prevent this,
|
||||
``mapping_populate`` command should be executed. It should be executed right after
|
||||
LDAP has been configured or after ``mapping_purge``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_populate --domain DOMAINA
|
||||
|
||||
Migrate domain-specific configuration files to the SQL database
|
||||
---------------------------------------------------------------
|
||||
|
||||
|
|
@ -64,6 +199,4 @@ domain name:
|
|||
|
||||
.. code-block:: console
|
||||
|
||||
# keystone-manage domain_config_upload --domain-name DOMAIN_NAME
|
||||
|
||||
|
||||
# keystone-manage domain_config_upload --domain-name DOMAIN_NAME
|
||||
|
|
@ -103,191 +103,13 @@ Keystone supports several different choices that will substantially impact how
|
|||
you'll configure, deploy, and interact with keystone.
|
||||
|
||||
You can also mix-and-match various sources of identity (see `Domain-specific
|
||||
Drivers`_ below for an example). For example, you can store OpenStack service
|
||||
users and their passwords in SQL, manage customers in LDAP, and authenticate
|
||||
employees via SAML federation.
|
||||
Configuration`_ for an example). For example, you can store OpenStack service users
|
||||
and their passwords in SQL, manage customers in LDAP, and authenticate employees
|
||||
via SAML federation.
|
||||
|
||||
.. _Domain-specific Configuration: admin/identity-domain-specific-config.html
|
||||
.. support_matrix:: identity-support-matrix.ini
|
||||
|
||||
.. Domain-specific Drivers:
|
||||
|
||||
Domain-specific Drivers
|
||||
-----------------------
|
||||
|
||||
Keystone supports the option (disabled by default) to specify identity driver
|
||||
configurations on a domain by domain basis, allowing, for example, a specific
|
||||
domain to have its own LDAP or SQL server. This is configured by specifying the
|
||||
following options:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[identity]
|
||||
domain_specific_drivers_enabled = True
|
||||
domain_config_dir = /etc/keystone/domains
|
||||
|
||||
Setting ``domain_specific_drivers_enabled`` to ``True`` will enable this
|
||||
feature, causing keystone to look in the ``domain_config_dir`` for config files
|
||||
of the form::
|
||||
|
||||
keystone.<domain_name>.conf
|
||||
|
||||
Options given in the domain specific configuration file will override those in
|
||||
the primary configuration file for the specified domain only. Domains without a
|
||||
specific configuration file will continue to use the options from the primary
|
||||
configuration file.
|
||||
|
||||
Keystone also supports the ability to store the domain-specific configuration
|
||||
options in the keystone SQL database, managed via the Identity API, as opposed
|
||||
to using domain-specific configuration files.
|
||||
|
||||
This capability (which is disabled by default) is enabled by specifying the
|
||||
following options in the main keystone configuration file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[identity]
|
||||
domain_specific_drivers_enabled = true
|
||||
domain_configurations_from_database = true
|
||||
|
||||
Once enabled, any existing domain-specific configuration files in the
|
||||
configuration directory will be ignored and only those domain-specific
|
||||
configuration options specified via the Identity API will be used.
|
||||
|
||||
Unlike the file-based method of specifying domain-specific configurations,
|
||||
options specified via the Identity API will become active without needing to
|
||||
restart the keystone server. For performance reasons, the current state of
|
||||
configuration options for a domain are cached in the keystone server, and in
|
||||
multi-process and multi-threaded keystone configurations, the new
|
||||
configuration options may not become active until the cache has timed out. The
|
||||
cache settings for domain config options can be adjusted in the general
|
||||
keystone configuration file (option ``cache_time`` in the ``domain_config``
|
||||
group).
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is important to notice that when using either of these methods of
|
||||
specifying domain-specific configuration options, the main keystone
|
||||
configuration file is still maintained. Only those options that relate
|
||||
to the Identity driver for users and groups (i.e. specifying whether the
|
||||
driver for this domain is SQL or LDAP, and, if LDAP, the options that
|
||||
define that connection) are supported in a domain-specific manner. Further,
|
||||
when using the configuration options via the Identity API, the driver
|
||||
option must be set to an LDAP driver (attempting to set it to an SQL driver
|
||||
will generate an error when it is subsequently used).
|
||||
|
||||
For existing installations that already use file-based domain-specific
|
||||
configurations who wish to migrate to the SQL-based approach, the
|
||||
``keystone-manage`` command can be used to upload all configuration files to
|
||||
the SQL database:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage domain_config_upload --all
|
||||
|
||||
Once uploaded, these domain-configuration options will be visible via the
|
||||
Identity API as well as applied to the domain-specific drivers. It is also
|
||||
possible to upload individual domain-specific configuration files by
|
||||
specifying the domain name:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage domain_config_upload --domain-name DOMAINA
|
||||
|
||||
.. NOTE::
|
||||
|
||||
It is important to notice that by enabling either of the domain-specific
|
||||
configuration methods, the operations of listing all users and listing all
|
||||
groups are not supported, those calls will need either a domain filter to
|
||||
be specified or usage of a domain scoped token.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Keystone does not support moving the contents of a domain (i.e. "its" users
|
||||
and groups) from one backend to another, nor group membership across
|
||||
backend boundaries.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
When using the file-based domain-specific configuration method, to delete a
|
||||
domain that uses a domain specific backend, it's necessary to first disable
|
||||
it, remove its specific configuration file (i.e. its corresponding
|
||||
keystone.<domain_name>.conf) and then restart the Identity server. When
|
||||
managing configuration options via the Identity API, the domain can simply
|
||||
be disabled and deleted via the Identity API; since any domain-specific
|
||||
configuration options will automatically be removed.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Although keystone supports multiple LDAP backends via the above
|
||||
domain-specific configuration methods, it currently only supports one SQL
|
||||
backend. This could be either the default driver or a single
|
||||
domain-specific backend, perhaps for storing service users in a
|
||||
predominantly LDAP installation.
|
||||
|
||||
.. NOTE::
|
||||
|
||||
Keystone has deprecated the ``keystone-manage domain_config_upload``
|
||||
option. The keystone team recommends setting domain config options via the
|
||||
API instead.
|
||||
|
||||
Due to the need for user and group IDs to be unique across an OpenStack
|
||||
installation and for keystone to be able to deduce which domain and backend to
|
||||
use from just a user or group ID, it dynamically builds a persistent identity
|
||||
mapping table from a public ID to the actual domain, local ID (within that
|
||||
backend) and entity type. The public ID is automatically generated by keystone
|
||||
when it first encounters the entity. If the local ID of the entity is from a
|
||||
backend that does not guarantee to generate UUIDs, a hash algorithm will
|
||||
generate a public ID for that entity, which is what will be exposed by
|
||||
keystone.
|
||||
|
||||
The use of a hash will ensure that if the public ID needs to be regenerated
|
||||
then the same public ID will be created. This is useful if you are running
|
||||
multiple keystones and want to ensure the same ID would be generated whichever
|
||||
server you hit.
|
||||
|
||||
While keystone will dynamically maintain the identity mapping, including
|
||||
removing entries when entities are deleted via the keystone, for those entities
|
||||
in backends that are managed outside of keystone (e.g. a read-only LDAP),
|
||||
keystone will not know if entities have been deleted and hence will continue to
|
||||
carry stale identity mappings in its table. While benign, keystone provides an
|
||||
ability for operators to purge the mapping table of such stale entries using
|
||||
the keystone-manage command, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
|
||||
|
||||
A typical usage would be for an operator to obtain a list of those entries in
|
||||
an external backend that had been deleted out-of-band to keystone, and then
|
||||
call keystone-manage to purge those entries by specifying the domain and
|
||||
local-id. The type of the entity (i.e. user or group) may also be specified if
|
||||
this is needed to uniquely identify the mapping.
|
||||
|
||||
Since public IDs can be regenerated **with the correct generator
|
||||
implementation**, if the details of those entries that have been deleted are
|
||||
not available, then it is safe to simply bulk purge identity mappings
|
||||
periodically, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --domain-name DOMAINA
|
||||
|
||||
will purge all the mappings for DOMAINA. The entire mapping table can be purged
|
||||
with the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_purge --all
|
||||
|
||||
Generating public IDs in the first run may take a while, and most probably
|
||||
first API requests to fetch user list will fail by timeout. To prevent this,
|
||||
``mapping_populate`` command should be executed. It should be executed right after
|
||||
LDAP has been configured or after ``mapping_purge``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ keystone-manage mapping_populate --domain DOMAINA
|
||||
|
||||
Public ID Generators
|
||||
--------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue