Information and recommendations for general configuration of keystone for keystone administrators. See the main Configuration section for complete keystone configuration documentation and sample config files.

Troubleshoot the Identity service

To troubleshoot the Identity service, review the logs in the /var/log/keystone/keystone.log file.

Use the /etc/keystone/logging.conf file to configure the location of log files.

The logs show the components that have come in to the WSGI request, and ideally show an error that explains why an authorization request failed. If you do not see the request in the logs, run keystone with the --debug parameter. Pass the --debug parameter before the command parameters.

Logging

You configure logging externally to the rest of Identity. The name of the file specifying the logging configuration is set using the log_config_append option in the [DEFAULT] section of the /etc/keystone/keystone.conf file. To route logging through syslog, set use_syslog=true in the [DEFAULT] section.

A sample logging configuration file is available with the project in etc/logging.conf.sample. Like other OpenStack projects, Identity uses the Python logging module, which provides extensive configuration options that let you define the output levels and formats.

Domain-specific configuration

The Identity service supports domain-specific Identity drivers. The drivers allow a domain to have its own LDAP or SQL back end. By default, domain-specific drivers are disabled.

Domain-specific Identity configuration options can be stored in domain-specific configuration files, or in the Identity SQL database using API REST calls.

Enable drivers for domain-specific configuration files

To enable domain-specific drivers, set these options in the /etc/keystone/keystone.conf file:

[identity]
domain_specific_drivers_enabled = True
domain_config_dir = /etc/keystone/domains

When you enable domain-specific drivers, Identity looks in the domain_config_dir directory for configuration files that are named as keystone.DOMAIN_NAME.conf. A domain without a domain-specific configuration file uses options in the primary configuration file.

Enable drivers for storing configuration options in SQL database

To enable domain-specific drivers, set these options in the /etc/keystone/keystone.conf file:

[identity]
domain_specific_drivers_enabled = True
domain_configurations_from_database = True

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).

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:

$ 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:

$ keystone-manage domain_config_upload --domain-name DOMAINA

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:

$ 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:

$ 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:

$ 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.

$ keystone-manage mapping_populate --domain DOMAINA

Public ID Generators

Keystone supports a customizable public ID generator and it is specified in the [identity_mapping] section of the configuration file. Keystone provides a sha256 generator as default, which produces regenerable public IDs. The generator algorithm for public IDs is a balance between key size (i.e. the length of the public ID), the probability of collision and, in some circumstances, the security of the public ID. The maximum length of public ID supported by keystone is 64 characters, and the default generator (sha256) uses this full capability. Since the public ID is what is exposed externally by keystone and potentially stored in external systems, some installations may wish to make use of other generator algorithms that have a different trade-off of attributes. A different generator can be installed by configuring the following property:

• generator – identity mapping generator. Defaults to sha256 (implemented by keystone.identity.id_generators.sha256.Generator)

Migrate domain-specific configuration files to the SQL database

You can use the keystone-manage command to migrate configuration options in domain-specific configuration files to the SQL database:

# keystone-manage domain_config_upload --all

To upload options from a specific domain-configuration file, specify the domain name:

# keystone-manage domain_config_upload --domain-name DOMAIN_NAME

Integrate Identity with LDAP

The OpenStack Identity service supports integration with existing LDAP directories for authentication and authorization services. LDAP back ends require initialization before configuring the OpenStack Identity service to work with it. For more information, see Setting up LDAP for use with Keystone.

When the OpenStack Identity service is configured to use LDAP back ends, you can split authentication (using the identity feature) and authorization (using the assignment feature). OpenStack Identity only supports read-only LDAP integration.

The identity feature enables administrators to manage users and groups by each domain or the OpenStack Identity service entirely.

The assignment feature enables administrators to manage project role authorization using the OpenStack Identity service SQL database, while providing user authentication through the LDAP directory.

Identity LDAP server set up