Keystone Configuration¶

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

Identity LDAP server set up¶

# setsebool -P authlogin_nsswitch_use_ldap on

The Identity configuration is split into two separate back ends; identity (back end for users and groups), and assignments (back end for domains, projects, roles, role assignments). To configure Identity, set options in the /etc/keystone/keystone.conf file. See Integrate Identity back end with LDAP for Identity back end configuration examples. Modify these examples as needed.

To define the destination LDAP server

Define the destination LDAP server in the /etc/keystone/keystone.conf file:

[ldap]
url = ldap://localhost
user = dc=Manager,dc=example,dc=org
password = samplepassword
suffix = dc=example,dc=org

Multiple LDAP servers can be supplied to url to provide high-availability support for a single LDAP backend. To specify multiple LDAP servers, simply change the url option in the [ldap] section to be a list, separated by commas:

url = "ldap://localhost,ldap://backup.localhost"

Additional LDAP integration settings

Set these options in the /etc/keystone/keystone.conf file for a single LDAP server, or /etc/keystone/domains/keystone.DOMAIN_NAME.conf files for multiple back ends. Example configurations appear below each setting summary:

Query option

[ldap]
query_scope = sub
page_size = 0
alias_dereferencing = default
chase_referrals =

Debug

Use debug_level to set the LDAP debugging level for LDAP calls. A value of zero means that debugging is not enabled.

[ldap]
debug_level = 4095

This setting sets OPT_DEBUG_LEVEL in the underlying python library. This field is a bit mask (integer), and the possible flags are documented in the OpenLDAP manpages. Commonly used values include 255 and 4095, with 4095 being more verbose and 0 being disabled. We recommend consulting the documentation for your LDAP back end when using this option.

Connection pooling

Various LDAP back ends use a common LDAP module to interact with LDAP data. By default, a new connection is established for each LDAP operation. This is expensive when TLS support is enabled, which is a likely configuration in an enterprise setup. Reusing connections from a connection pool drastically reduces overhead of initiating a new connection for every LDAP operation.

Use use_pool to enable LDAP connection pooling. Configure the connection pool size, maximum retry, reconnect trials, timeout (-1 indicates indefinite wait) and lifetime in seconds.

[ldap]
use_pool = true
pool_size = 10
pool_retry_max = 3
pool_retry_delay = 0.1
pool_connection_timeout = -1
pool_connection_lifetime = 600

Connection pooling for end user authentication

LDAP user authentication is performed via an LDAP bind operation. In large deployments, user authentication can use up all available connections in a connection pool. OpenStack Identity provides a separate connection pool specifically for user authentication.

Use use_auth_pool to enable LDAP connection pooling for end user authentication. Configure the connection pool size and lifetime in seconds. Both use_pool and use_auth_pool must be enabled to pool connections for user authentication.

[ldap]
use_auth_pool = false
auth_pool_size = 100
auth_pool_connection_lifetime = 60

When you have finished the configuration, restart the OpenStack Identity service.

Integrate Identity back end with LDAP¶

The Identity back end contains information for users, groups, and group member lists. Integrating the Identity back end with LDAP allows administrators to use users and groups in LDAP.

To integrate one Identity back end with LDAP

1. Enable the LDAP Identity driver in the /etc/keystone/keystone.conf file. This allows LDAP as an identity back end:

   [identity]
   #driver = sql
   driver = ldap
   

2. Create the organizational units (OU) in the LDAP directory, and define the corresponding location in the /etc/keystone/keystone.conf file:

   [ldap]
   user_tree_dn = ou=Users,dc=example,dc=org
   user_objectclass = inetOrgPerson
   
   group_tree_dn = ou=Groups,dc=example,dc=org
   group_objectclass = groupOfNames
   

   Note

   These schema attributes are extensible for compatibility with various schemas. For example, this entry maps to the person attribute in Active Directory:

   user_objectclass = person
   

   Restart the OpenStack Identity service.

   Warning

   During service restart, authentication and authorization are unavailable.

To integrate multiple Identity back ends with LDAP

1. Set the following options in the /etc/keystone/keystone.conf file:

   1. Enable the LDAP driver:

      [identity]
      #driver = sql
      driver = ldap
      

   2. Enable domain-specific drivers:

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

2. Restart the OpenStack Identity service.

   Warning

   During service restart, authentication and authorization are unavailable.

3. List the domains using the dashboard, or the OpenStackClient CLI. Refer to the Command List for a list of OpenStackClient commands.

4. Create domains using OpenStack dashboard, or the OpenStackClient CLI.

5. For each domain, create a domain-specific configuration file in the /etc/keystone/domains directory. Use the file naming convention keystone.DOMAIN_NAME.conf, where DOMAIN_NAME is the domain name assigned in the previous step.

   Note

   The options set in the /etc/keystone/domains/keystone.DOMAIN_NAME.conf file will override options in the /etc/keystone/keystone.conf file.

6. Define the destination LDAP server in the /etc/keystone/domains/keystone.DOMAIN_NAME.conf file. For example:

   [ldap]
   url = ldap://localhost
   user = dc=Manager,dc=example,dc=org
   password = samplepassword
   suffix = dc=example,dc=org
   

7. Create the organizational units (OU) in the LDAP directories, and define their corresponding locations in the /etc/keystone/domains/keystone.DOMAIN_NAME.conf file. For example:

   [ldap]
   user_tree_dn = ou=Users,dc=example,dc=org
   user_objectclass = inetOrgPerson
   
   group_tree_dn = ou=Groups,dc=example,dc=org
   group_objectclass = groupOfNames
   

   Note

   These schema attributes are extensible for compatibility with various schemas. For example, this entry maps to the person attribute in Active Directory:

   user_objectclass = person
   

8. Restart the OpenStack Identity service.

   Warning

   During service restart, authentication and authorization are unavailable.

Additional LDAP integration settings

Set these options in the /etc/keystone/keystone.conf file for a single LDAP server, or /etc/keystone/domains/keystone.DOMAIN_NAME.conf files for multiple back ends. Example configurations appear below each setting summary:

Filters

Use filters to control the scope of data presented through LDAP.

[ldap]
user_filter = (memberof=cn=openstack-users,ou=workgroups,dc=example,dc=org)
group_filter =

Identity attribute mapping

Mask account status values (include any additional attribute mappings) for compatibility with various directory services. Superfluous accounts are filtered with user_filter.

Setting attribute ignore to list of attributes stripped off on update.

For example, you can mask Active Directory account status attributes in the /etc/keystone/keystone.conf file:

[ldap]
user_id_attribute      = cn
user_name_attribute    = sn
user_mail_attribute    = mail
user_pass_attribute    = userPassword
user_enabled_attribute = userAccountControl
user_enabled_mask      = 2
user_enabled_invert    = false
user_enabled_default   = 512
user_default_project_id_attribute =
user_additional_attribute_mapping =

group_id_attribute     = cn
group_name_attribute   = ou
group_member_attribute = member
group_desc_attribute   = description
group_additional_attribute_mapping =

It is possible to model more complex LDAP schemas. For example, in the user object, the objectClass posixAccount from RFC2307 is very common. If this is the underlying objectClass, then the uid field should probably be uidNumber and the username field should be either uid or cn. The following illustrates the configuration:

[ldap]
user_id_attribute = uidNumber
user_name_attribute = cn

Enabled emulation

OpenStack Identity supports emulation for integrating with LDAP servers that do not provide an enabled attribute for users. This allows OpenStack Identity to advertise enabled attributes when the user entity in LDAP does not. The user_enabled_emulation option must be enabled and the user_enabled_emulation_dn option must be a valid LDAP group. Users in the group specified by user_enabled_emulation_dn will be marked as enabled. For example, the following will mark any user who is a member of the enabled_users group as enabled:

[ldap]
user_enabled_emulation = True
user_enabled_emulation_dn = cn=enabled_users,cn=groups,dc=openstack,dc=org

If the directory server has an enabled attribute, but it is not a boolean type, a mask can be used to convert it. This is useful when the enabled attribute is an integer value. The following configuration highlights the usage:

[ldap]
user_enabled_attribute = userAccountControl
user_enabled_mask = 2
user_enabled_default = 512

In this case, the attribute is an integer and the enabled attribute is listed in bit 1. If the mask configured user_enabled_mask is different from 0, it retrieves the attribute from user_enabled_attribute and performs an add operation with the user_enabled_mask. If the sum of the operation matches the mask, then the account is disabled.

The value of user_enabled_attribute is also saved before applying the add operation in enabled_nomask. This is done in case the user needs to be enabled or disabled. Lastly, setting user_enabled_default is needed in order to create a default value on the integer attribute (512 = NORMAL ACCOUNT in Active Directory).

When you have finished configuration, restart the OpenStack Identity service.

Secure the OpenStack Identity service connection to an LDAP back end¶

We recommend securing all connections between OpenStack Identity and LDAP. The Identity service supports the use of TLS to encrypt LDAP traffic. Before configuring this, you must first verify where your certificate authority file is located. For more information, see the OpenStack Security Guide SSL introduction.

Once you verify the location of your certificate authority file:

To configure TLS encryption on LDAP traffic

1. Open the /etc/keystone/keystone.conf configuration file.

2. Find the [ldap] section.

3. In the [ldap] section, set the use_tls configuration key to True. Doing so will enable TLS.

4. Configure the Identity service to use your certificate authorities file. To do so, set the tls_cacertfile configuration key in the ldap section to the certificate authorities file’s path.

   Note

   You can also set the tls_cacertdir (also in the ldap section) to the directory where all certificate authorities files are kept. If both tls_cacertfile and tls_cacertdir are set, then the latter will be ignored.

5. Specify what client certificate checks to perform on incoming TLS sessions from the LDAP server. To do so, set the tls_req_cert configuration key in the [ldap] section to demand, allow, or never:

   demand - The LDAP server always receives certificate requests. The session terminates if no certificate is provided, or if the certificate provided cannot be verified against the existing certificate authorities file. allow - The LDAP server always receives certificate requests. The session will proceed as normal even if a certificate is not provided. If a certificate is provided but it cannot be verified against the existing certificate authorities file, the certificate will be ignored and the session will proceed as normal. never - A certificate will never be requested.

When you have finished configuration, restart the OpenStack Identity service.

On distributions that include openstack-config, you can configure TLS encryption on LDAP traffic by running the following commands instead.

# openstack-config --set /etc/keystone/keystone.conf \
  ldap use_tls True
# openstack-config --set /etc/keystone/keystone.conf \
  ldap tls_cacertfile ``CA_FILE``
# openstack-config --set /etc/keystone/keystone.conf \
  ldap tls_req_cert ``CERT_BEHAVIOR``

Where:

• CA_FILE is the absolute path to the certificate authorities file that should be used to encrypt LDAP traffic.

• CERT_BEHAVIOR specifies what client certificate checks to perform on an incoming TLS session from the LDAP server (demand, allow, or never).

Caching for tokens and tokens validation¶

The token subsystem is OpenStack Identity’s most heavily used API. As a result, all types of tokens benefit from caching, including Fernet tokens. Although Fernet tokens do not need to be persisted, they should still be cached for optimal token validation performance.

The token system has a separate cache_time configuration option, that can be set to a value above or below the global expiration_time default, allowing for different caching behavior from the other systems in OpenStack Identity. This option is set in the [token] section of the configuration file.

The token revocation list cache time is handled by the configuration option revocation_cache_time in the [token] section. The revocation list is refreshed whenever a token is revoked. It typically sees significantly more requests than specific token retrievals or token validation calls.

Here is a list of actions that are affected by the cached time:

• getting a new token

• revoking tokens

• validating tokens

• checking v3 tokens

The delete token API calls invalidate the cache for the tokens being acted upon, as well as invalidating the cache for the revoked token list and the validate/check token calls.

Token caching is configurable independently of the revocation_list caching. Lifted expiration checks from the token drivers to the token manager. This ensures that cached tokens will still raise a TokenNotFound flag when expired.

For cache consistency, all token IDs are transformed into the short token hash at the provider and token driver level. Some methods have access to the full ID (PKI Tokens), and some methods do not. Cache invalidation is inconsistent without token ID normalization.

Caching for non-token resources¶

Various other keystone components have a separate cache_time configuration option, that can be set to a value above or below the global expiration_time default, allowing for different caching behavior from the other systems in Identity service. This option can be set in various sections (for example, [role] and [resource]) of the configuration file. The create, update, and delete actions for domains, projects and roles will perform proper invalidations of the cached methods listed above.

For more information about the different back ends (and configuration options), see:

• dogpile.cache.memory

• dogpile.cache.memcached

  Note

  The memory back end is not suitable for use in a production environment.

• dogpile.cache.redis

• dogpile.cache.dbm

Cache invalidation¶

A common concern with caching is relaying inaccurate information after updating or deleting a resource. Most subsystems within OpenStack Identity invalidate specific cache entries once they have changed. In cases where a specific cache entry cannot be invalidated from the cache, the cache region will be invalidated instead. This invalidates all entries within the cache to prevent returning stale or misleading data. A subsequent request for the resource will be fully processed and cached.

Configure the Memcached back end example¶

The following example shows how to configure the memcached back end:

[cache]

enabled = true
backend = dogpile.cache.memcached
backend_argument = url:127.0.0.1:11211

You need to specify the URL to reach the memcached instance with the backend_argument parameter.

Verbose cache logging¶

We do not recommend using verbose cache logging by default in production systems since it’s extremely noisy. However, you may need to debug cache issues. One way to see how keystone is interacting with a cache backend is to enhance logging. The following configuration will aggregate oslo and dogpile logs into keystone’s log file with increased verbosity:

[DEFAULT]
default_log_levels = oslo.cache=DEBUG,dogpile.core.dogpile=DEBUG

[cache]
debug_cache_backend = True

These logs will include cache hits and misses, making it easier to diagnose cache configuration and connectivity issues.

Setting an account lockout threshold¶

The account lockout feature limits the number of incorrect password attempts. If a user fails to authenticate after the maximum number of attempts, the service disables the user. Users can be re-enabled by explicitly setting the enable user attribute with the update user v3 API call.

You set the maximum number of failed authentication attempts by setting the lockout_failure_attempts:

[security_compliance]
lockout_failure_attempts = 6

You set the number of minutes a user would be locked out by setting the lockout_duration in seconds:

[security_compliance]
lockout_duration = 1800

If you do not set the lockout_duration, users will be locked out indefinitely until the user is explicitly enabled via the API.

You can ensure specific users are never locked out. This can be useful for service accounts or administrative users. You can do this by setting the user option for ignore_lockout_failure_attempts.

Disabling inactive users¶

PCI-DSS 8.1.4 requires that inactive user accounts be removed or disabled within 90 days. You can achieve this by setting the disable_user_account_days_inactive:

[security_compliance]
disable_user_account_days_inactive = 90

This above example means that users that have not authenticated (inactive) for the past 90 days are automatically disabled. Users can be re-enabled by explicitly setting the enable user attribute via the API.

Force users to change password upon first use¶

PCI-DSS 8.2.6 requires users to change their password for first time use and upon an administrative password reset. Within the identity user API, create user and update user are considered administrative password changes. Whereas, change password for user is a self-service password change. Once this feature is enabled, new users, and users that have had their password reset, will be required to change their password upon next authentication (first use), before being able to access any services.

Prior to enabling this feature, you may want to exempt some users that you do not wish to be required to change their password. You can mark a user as exempt by setting the user options attribute ignore_change_password_upon_first_use.

When ready, you can configure it so that users are forced to change their password upon first use by setting change_password_upon_first_use:

[security_compliance]
change_password_upon_first_use = True

Configuring password expiration¶

Passwords can be configured to expire within a certain number of days by setting the password_expires_days:

[security_compliance]
password_expires_days = 90

Once set, any new password changes have an expiration date based on the date/time of the password change plus the number of days defined here. Existing passwords will not be impacted. If you want existing passwords to have an expiration date, you would need to run a SQL script against the password table in the database to update the expires_at column.

If there exists a user whose password you do not want to expire, keystone supports setting that via the user option ignore_password_expiry.

Configuring password strength requirements¶

You can set password strength requirements, such as requiring numbers in passwords or setting a minimum password length, by adding a regular expression to the password_regex setting:

[security_compliance]
password_regex = ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$

The above example is a regular expression that requires a password to have:

• One (1) letter

• One (1) digit

• Minimum length of seven (7) characters

If you do set the password_regex, you should provide text that describes your password strength requirements. You can do this by setting the password_regex_description:

[security_compliance]
password_regex_description = Passwords must contain at least 1 letter, 1
                             digit, and be a minimum length of 7
                             characters.

It is imperative that the password_regex_description matches the actual regex. If the password_regex and the password_regex_description do not match, it will cause user experience to suffer since this description will be returned to users to explain why their requested password was insufficient.

Requiring a unique password history¶

The password history requirements controls the number of passwords for a user that must be unique before an old password can be reused. You can enforce this by setting the unique_last_password_count:

[security_compliance]
unique_last_password_count= 5

The above example does not allow a user to create a new password that is the same as any of their last four previous passwords.

Similarly, you can set the number of days that a password must be used before the user can change it by setting the minimum_password_age:

[security_compliance]
minimum_password_age = 1

In the above example, once a user changes their password, they would not be able to change it again for one day. This prevents users from changing their passwords immediately in order to wipe out their password history and reuse an old password.

Prevent Self-Service Password Changes¶

If there exists a user who should not be able to change her own password via the keystone password change API, keystone supports setting that via the user option lock_password.

This is typically used in the case where passwords are managed externally to keystone.

Keystone configuration options that affect performance¶

These are all of the options in keystone.conf that have a direct impact on performance. See the help descriptions for these options for more specific details on how and why you might want to tune these options for yourself.

• [DEFAULT] max_project_tree_depth: Reduce this number to increase performance, increase this number to cater to more complicated hierarchical multitenancy use cases.

• [DEFAULT] max_password_length: Reduce this number to increase performance, increase this number to allow for more secure passwords.

• [cache] enable: Enable this option to increase performance, but you also need to configure other options in the [cache] section to actually utilize caching.

• [token] provider: All supported token providers have been primarily driven by performance considerations. UUID and Fernet both require online validation (cacheable HTTP calls back to keystone to validate tokens). Fernet has the highest scalability characteristics overall, but requires more work to validate, and therefore enabling caching ([cache] enable) is absolutely critical.

• [fernet] max_active_keys: If you’re using Fernet tokens, decrease this option to improve performance, increase this option to support more advanced key rotation strategies.

Keystonemiddleware configuration options that affect performance¶

This configuration actually lives in the Paste pipelines of services consuming token validation from keystone (i.e.: nova, cinder, swift, etc.).

• cache: When keystone’s auth_token middleware is deployed with a swift cache, use this option to have auth_token middleware share a caching backend with swift. Otherwise, use the memcached_servers option instead.

• memcached_servers: Set this option to share a cache across keystonemiddleware.auth_token processes.

• token_cache_time: Increase this option to improve performance, decrease this option to respond to token revocation events more quickly (thereby increasing security).

• revocation_cache_time: Increase this option to improve performance, decrease this option to respond to token revocation events more quickly (thereby increasing security).

• memcache_security_strategy: Do not set this option to improve performance, but set it to improve security where you’re sharing memcached with other processes.

• include_service_catalog: Disable this option to improve performance, if the protected service does not require a service catalog.