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

[identity]
domain_specific_drivers_enabled = True
domain_configurations_from_database = True

$ keystone-manage domain_config_upload --all

$ keystone-manage domain_config_upload --domain-name DOMAINA

$ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com

$ keystone-manage mapping_purge --domain-name DOMAINA

$ keystone-manage mapping_purge --all

$ keystone-manage mapping_populate --domain DOMAINA

# keystone-manage domain_config_upload --all

# keystone-manage domain_config_upload --domain-name DOMAIN_NAME

# setsebool -P authlogin_nsswitch_use_ldap on

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

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

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

[ldap]
debug_level = 4095

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

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

[identity]
#driver = sql
driver = ldap

[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

user_objectclass = person

[identity]
#driver = sql
driver = ldap

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

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

[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

user_objectclass = person

8. Restart the OpenStack Identity service.

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.

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 layer

OpenStack Identity supports a caching layer that is above the configurable subsystems (for example, token). This gives you the flexibility to setup caching for all or some subsystems. OpenStack Identity uses the oslo.cache library which allows flexible cache back ends. The majority of the caching configuration options are set in the [cache] section of the /etc/keystone/keystone.conf file. The enabled option of the [cache] section must be set to True in order for any subsystem to cache responses. Each section that has the capability to be cached will have a caching boolean value that toggles caching behavior of that particular subsystem.

So to enable only the token back end caching, set the values as follows:

[cache]
enabled=true

[catalog]
caching=false

[domain_config]
caching=false

[federation]
caching=false

[resource]
caching=false

[revoke]
caching=false

[role]
caching=false

[token]
caching=true

Current functional back ends are:dogpile.cache.null

A “null” backend that effectively disables all cache operations.(Default)dogpile.cache.memcached

Memcached back end using the standard python-memcached library.dogpile.cache.pylibmc

Memcached back end using the pylibmc library.dogpile.cache.bmemcached

Memcached using the python-binary-memcached library.dogpile.cache.redis

Redis back end.dogpile.cache.dbm

Local DBM file back end.dogpile.cache.memory

In-memory cache, not suitable for use outside of testing as it does not cleanup its internal cache on cache expiration and does not share cache between processes. This means that caching and cache invalidation will not be consistent or reliable.dogpile.cache.memory_pickle

In-memory cache, but serializes objects with pickle lib. It’s not suitable for use outside of testing. The reason is the same with dogpile.cache.memoryoslo_cache.mongo

MongoDB as caching back end.oslo_cache.memcache_pool

Memcached backend that does connection pooling.oslo_cache.etcd3gw

Uses etcd 3.x for storage.oslo_cache.dict

A DictCacheBackend based on dictionary, not suitable for use outside of testing as it does not share cache between processes.This means that caching and cache invalidation will not be consistent or reliable.

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

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

Security compliance and PCI-DSS

As of the Newton release, the Identity service contains additional security compliance features, specifically to satisfy Payment Card Industry – Data Security Standard (PCI-DSS) v3.1 requirements. See Security Hardening PCI-DSS for more information on PCI-DSS.

Security compliance features are disabled by default and most of the features only apply to the SQL backend for the identity driver. Other identity backends, such as LDAP, should implement their own security controls.

Enable these features by changing the configuration settings under the [security_compliance] section in keystone.conf.

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.

Performance and scaling

Before you begin tuning Keystone for performance and scalability, you should first know that Keystone is just a two tier horizontally-scalable web application, and the most effective methods for scaling it are going to be the same as for any other similarly designed web application: give it more processes, more memory, scale horizontally, and load balance the result.

With that said, there are many opportunities for tuning the performance of Keystone, many of which are actually trade-offs between performance and security that you need to judge for yourself, and tune accordingly.

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.

URL safe naming of projects and domains

In the future, keystone may offer the ability to identify a project in a hierarchy via a URL style of naming from the root of the hierarchy (for example specifying ‘projectA/projectB/projectC’ as the project name in an authentication request). In order to prepare for this, keystone supports the optional ability to ensure both projects and domains are named without including any of the reserved characters specified in section 2.2 of rfc3986.

The safety of the names of projects and domains can be controlled via two configuration options:

[resource]
project_name_url_safe = off
domain_name_url_safe = off

When set to off (which is the default), no checking is done on the URL safeness of names. When set to new, an attempt to create a new project or domain with an unsafe name (or update the name of a project or domain to be unsafe) will cause a status code of 400 (Bad Request) to be returned. Setting the configuration option to strict will, in addition to preventing the creation and updating of entities with unsafe names, cause an authentication attempt which specifies a project or domain name that is unsafe to return a status code of 401 (Unauthorized).

It is recommended that installations take the steps necessary to where they can run with both options set to strict as soon as is practical.

Limiting list return size

Keystone provides a method of setting a limit to the number of entities returned in a collection, which is useful to prevent overly long response times for list queries that have not specified a sufficiently narrow filter. This limit can be set globally by setting list_limit in the default section of keystone.conf, with no limit set by default. Individual driver sections may override this global value with a specific limit, for example:

[resource]
list_limit = 100

If a response to list_{entity} call has been truncated, then the response status code will still be 200 (OK), but the truncated attribute in the collection will be set to true.

Endpoint Filtering

Endpoint Filtering enables creation of ad-hoc catalogs for each project-scoped token request.

Configure the endpoint filter catalog driver in the [catalog] section. For example:

[catalog]
driver = catalog_sql

In the [endpoint_filter] section, set return_all_endpoints_if_no_filter to False to return an empty catalog if no associations are made. For example:

[endpoint_filter]
return_all_endpoints_if_no_filter = False

See API Specification for Endpoint Filtering for the details of API definition.

Endpoint Policy

The Endpoint Policy feature provides associations between service endpoints and policies that are already stored in the Identity server and referenced by a policy ID.

Configure the endpoint policy backend driver in the [endpoint_policy] section. For example:

[endpoint_policy]
driver = sql

See API Specification for Endpoint Policy for the details of API definition.