Pike Series Release Notes¶

New Features¶

• [`blueprint policy-in-code] Keystone now supports the ability to register default policies in code. This makes policy file maintenance easier by allowing duplicated default policies to be removed from the policy file. The only policies that should exist within a deployment’s policy file after Pike should be policy overrides. Note that there is no longer a default value for the default rule. That rule is only checked when the more specific rule cannot be found, and with policy in code all rules should be found in code even if they are not in the policy file. To generate sample policy files from default values, prune default policies from existing policy files, or familiarize yourself with general policy usage, please see the usage documentation provided in oslo.policy.

• Added an option --check to keystone-manage db_sync, the option will allow a user to check the status of rolling upgrades in the database.

• • [bug 1543048] [bug 1668503] Keystone now supports multiple forms of password hashing. Notably bcrypt, scrypt, and pbkdf2_sha512. The options are now located in the [identity] section of the configuration file. To set the algorithm use [identity] password_hash_algorithm. To set the number of rounds (time-complexity, and memory-use in the case of scrypt) use [identity] password_hash_rounds. scrypt and pbkdf2_sha512 have further tuning options available. Keystone now defaults to using bcrypt as the hashing algorithm. All passwords will continue to function with the old sha512_crypt hash, but new password hashes will be bcrypt.

Upgrade Notes¶

• [`blueprint policy-in-code] Keystone now supports the ability to register default policies in code. This makes policy file maintenance easier by allowing duplicated default policies to be removed from the policy file. The only policies that should exist within a deployment’s policy file after Pike should be policy overrides. Note that there is no longer a default value for the default rule. That rule is only checked when the more specific rule cannot be found, and with policy in code all rules should be found in code even if they are not in the policy file. To generate sample policy files from default values, prune default policies from existing policy files, or familiarize yourself with general policy usage, please see the usage documentation provided in oslo.policy.

• The identity backend driver interface has changed. A new method, unset_default_project_id(project_id), was added to unset a user’s default project ID for a given project ID. Custom backend implementations must implement this method.

• [bug 1702211] Password created_at field under some versions/deployments of MySQL would lose sub-second precision. This means that it was possible for passwords to be returned out-of-order when changed within one second (especially common in testing). This change stores password created_at and expires_at as an integer instead of as a DATETIME data-type.

• [bug 1705485] The change_password protection policy can be removed from file-based policies. This policy is no longer used to protect the self-service password change API since the logic was moved into code. Note that the administrative password reset functionality is still protected via policy on the update_user API.

• • If performing rolling upgrades, set [identity] rolling_upgrade_password_hash_compat to True. This will instruct keystone to continue to hash passwords in a manner that older (pre Pike release) keystones can still verify passwords. Once all upgrades are complete, ensure this option is set back to False.

• The resource backend cannot be configured to anything but SQL if the SQL Identity backend is being used. The resource backend must now be SQL which allows for the use of Foreign Keys to domains/projects wherever desired. This makes managing project relationships and such much more straight forward. The inability to configure non-SQL resource backends has been in Keystone since at least Ocata. This is eliminating some complexity and preventing the need for some really ugly back-port SQL migrations in favor of a better model. Resource is highly relational and should be SQL based.

Deprecation Notes¶

• • [DEFAULT] crypt_strength is deprecated in favor of [identity] password_hash_rounds. Note that [DEFAULT] crypt_strength is still used when [identity] rolling_upgrade_password_hash_compat is set to True.

• • UUID token provider [token] provider=uuid has been deprecated in favor of Fernet tokens [token] provider=fernet. With Fernet tokens becoming the default UUID tokens can be slated for removal in the R release. This also deprecates token-bind support as it was never implemented for fernet.
  • Token persistence driver/code (SQL) is deprecated with this patch since it is only used by the UUID token provider..

• [blueprint deprecated-as-of-pike] The v2.0 auth and ec2 APIs were already maked as deprecated in the Mitaka release, although no removal release had yet been identified. These APIs will now be removed in the ‘T’ release. The v3 APIs should be used instead.

Security Issues¶

• [bug 1703369] There was a typo for the identity:get_identity_provider rule in the default policy.json file in previous releases. The default value for that rule was the same as the default value for the default rule (restricted to admin) so this typo was not readily apparent. Anyone customizing this rule should review their settings and confirm that they did not copy that typo. Particularly given that the default rule is being removed in Pike with the move of policy into code.

• • The use of sha512_crypt is considered inadequate for password hashing in an application like Keystone. The use of bcrypt or scrypt is recommended to ensure protection against password cracking utilities if the hashes are exposed. This is due to Time-Complexity requirements for computing the hashes in light of modern hardware (CPU, GPU, ASIC, FPGA, etc). Keystone has moved to bcrypt as a default and no longer hashes new passwords (and password changes) with sha512_crypt. It is recommended passwords be changed after upgrade to Pike. The risk of password hash exposure is limited, but for the best possible protection against cracking the hash it is recommended passwords be changed after upgrade. The password change will then result in a more secure hash (bcrypt by default) being used to store the password in the DB.

Bug Fixes¶

• [bug 1523369] Deleting a project will now cause it to be removed as a default project for users. If caching is enabled the changes may not be visible until the user’s cache entry expires.

• [bug 1615014] Migration order is now strictly enforced. The ensure upgrade process is done in the order it is officially documented and support, starting with expand, then migrate, and finishing with contract.

• [bug 1689616] Significant improvements have been made when performing a token flush on massive data sets.

• [bug 1670382] The ldap config group_members_are_ids has been added to the whitelisted options allowing it to now be used in the domain config API and keystone-manage domain_config_upload

• [bug 1676497] bindep now correctly reports the openssl-devel binary dependency for rpm distros instead of libssl-dev.

• [bug 1684994] This catches the ldap.INVALID_CREDENTIALS exception thrown when trying to connect to an LDAP backend with an invalid username or password, and emits a message back to the user instead of the default 500 error message.

• [bug 1687593] Ensure that the URL used to make the request when creating OAUTH1 request tokens is also the URL that verifies the request token.

• [bug 1696574] All GET APIs within keystone now have support for HEAD, if not already implemented. All new HEAD APIs have the same response codes and headers as their GET counterparts. This aids in client-side processing, especially caching.

• [bug 1700852] Keystone now supports caching of the GET|HEAD /v3/users/{user_id}/projects API in an effort to improve performance.

• [bug 1701324] Token bodies now contain only unique roles in the authentication response.

• [bug 1704205] All users and groups are required to have a name. Prior to this fix, Keystone was not properly enforcing this for LDAP users and groups. Keystone will now ignore users and groups that do not have a value for the LDAP attribute which Keystone has been configured to use for that entity’s name.

• [bug 1705485] A previous change removed policy from the self-service password API. Since a user is required to authenticate to change their password, protection via policy didn’t necessarily make sense. This change removes the default policy from code, since it is no longer required or used by the service. Note that administrative password resets for users are still protected via policy through a separate endpoint.

• [bug 1674415] Fixed issue with translation of keystone error messages which was not happening in case of any error messages from identity API with locale being set.

• [bug 1688188] When creating an IdP, if a domain was generated for it and a conflict was raised while effectively creating the IdP in the database, the auto-generated domain is now cleaned up.

• The implementation for checking database state during an upgrade with the use of keystone-manage db_sync –check has been corrected. This allows users and automation to determine what step is next in a rolling upgrade based on logging and command status codes.

Other Notes¶

• [blueprint removed-as-of-pike] All key-value-store code, options, and documentation has been removed as of the Pike release. The removed code included keystone.common.kvs configuration options for the KVS code, unit tests, and the KVS token persistence driver keystone.token.persistence.backends.kvs. All associated documentation has been removed.

• [blueprint removed-as-of-pike] The admin_token_auth filter has been removed from all sample pipelines, specifically, the following section has been removed from keystone-paste.ini:

  [filter:admin_token_auth]
  use = egg:keystone#admin_token_auth
  

  The functionality of the ADMIN_TOKEN remains, but has been incorporated into the main auth middleware (keystone.middleware.auth.AuthContextMiddleware).

• The catalog backend endpoint_filter.sql has been removed. It has been consolidated with the sql backend, therefore replace the endpoint_filter.sql catalog backend with the sql backend.

• The [security_compliance] password_expires_ignore_user_ids option has been removed. Each user that should ignore password expiry should have the value set to “true” in the user’s options attribute (e.g. user['options']['ignore_password_expiry'] = True) with a user update call.

• [blueprint removed-as-of-pike] The keystone.common.ldap module was removed from the code tree. It was deprecated in the Newton release in favor of using keystone.identity.backends.ldap.common which has the same functionality.

• [blueprint removed-as-of-pike] The keystone-manage pki_setup was added to aid developer setup by hiding the sometimes cryptic openssl commands. This is no longer needed since keystone no longer supports PKI tokens and can no longer serve SSL. This was deprecated in the Mitaka release.

• [blueprint removed-as-of-pike] Direct import of drivers outside of their keystone namespace has been removed. Ex. identity drivers are loaded from the keystone.identity namespace and assignment drivers from the keystone.assignment namespace. Loading drivers outside of their keystone namespaces was deprecated in the Liberty release.