diff --git a/doc/admin-guide-cloud/ch_identity_mgmt.xml b/doc/admin-guide-cloud/ch_identity_mgmt.xml index 5fd1bbf447..75b69c1ecc 100644 --- a/doc/admin-guide-cloud/ch_identity_mgmt.xml +++ b/doc/admin-guide-cloud/ch_identity_mgmt.xml @@ -4,15 +4,15 @@ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ch-identity-mgmt-config"> Identity management - The OpenStack Identity Service, code-named keystone, is the + OpenStack Identity, code-named keystone, is the default identity management system for OpenStack. After you - install the Identity Service, you configure it through the + install Identity, you configure it through the etc/keystone.conf configuration file and, possibly, a separate logging configuration file. You initialize - data into the Identity Service by using the + data into Identity by using the keystone command-line client.
- Identity Service concepts + Identity concepts
User CRUD - The Identity Service provides a user CRUD filter that can + Identity provides a user CRUD filter that can be added to the public_api pipeline. This user CRUD filter enables users to use a HTTP PATCH to change their own password. To enable this extension you should define a @@ -44,16 +44,15 @@ paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory [pipeline:public_api] pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension user_crud_extension public_service Each user can then change their own password with a HTTP PATCH: - $ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<userid> -H "Content-type: application/json" \ - -H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}' - In addition to changing their password, all of the user's current - tokens are deleted (if the back-end is KVS or sql). - Only use a KVS backend for tokens when testing. + $ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/USERID -H "Content-type: application/json" \ + -H "X_Auth_Token: AUTHTOKENID" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}' + In addition to changing their password, all current + tokens for the user are deleted (if the back end is KVS or sql). + Only use a KVS back end for tokens when testing.
Logging - You configure logging externally to the rest of the Identity - Service. The file specifying the logging configuration is in the + You configure logging externally to the rest of Identity. The file specifying the logging configuration is in the [DEFAULT] section of the keystone.conf file under log_config. To route logging through @@ -61,7 +60,7 @@ pipeline = stats_monitoring url_normalize token_auth admin_token_auth xml_body j [DEFAULT] section. A sample logging file is available with the project in the etc/logging.conf.sample directory. Like - other OpenStack projects, the Identity Service uses the Python + other OpenStack projects, Identity uses the Python logging module, which includes extensive configuration options that let you define the output levels and formats. Review the etc/keystone.conf sample @@ -100,7 +99,7 @@ admin_tenant_name = service
Monitoring - The Identity Service provides some basic request/response + Identity provides some basic request and response monitoring statistics out of the box. Enable data collection by defining a stats_monitoring filter and including it at @@ -127,8 +126,8 @@ pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service
- Start the Identity Service - To start the services for the Identity Service, run the + Start the Identity services + To start the services for Identity, run the following command: $ keystone-all This command starts two wsgi.Server instances configured by @@ -172,7 +171,7 @@ keystone --username=admin --password=secrete --tenant_name=admin tenant-create -
Authentication middleware with user name and password - You can also configure the Identity Service authentication + You can also configure Identity authentication middleware using the and options. When using the and @@ -226,6 +225,94 @@ admin_password = keystone123 role on the admin tenant.
+
+ Identity API protection with role-based access control (RBAC) + + Like most OpenStack projects, Identity supports the protection of + its APIs by defining policy rules based on an RBAC approach. Identity + stores a reference to a policy JSON file in the main Identity + configuration file, keystone.conf. Typically this + file is named policy.json, and it contains the rules + for which roles have access to certain actions in defined services. + Each Identity API v3 call has a line in the policy file that dictates which + level of governance of access applies. + API_NAME: RULE_STATEMENT or MATCH_STATEMENT + Where: + RULE_STATEMENT can contain RULE_STATEMENT or MATCH_STATEMENT. + MATCH_STATEMENT is a set of identifiers that must match between the token + provided by the caller of the API and the parameters or target entities of + the API call in question. For example: + "identity:create_user": [["role:admin", "domain_id:%(user.domain_id)s"]] + Indicates that to create a user, you must have the admin role in your token and + the domain_id in your token (which implies this must be a domain-scoped token) + must match the domain_id in the user object that you are trying to + create. In other words, you must have the admin role on the domain in which + you are creating the user, and the token that you use must be scoped to that + domain. + Each component of a match statement uses this format: + ATTRIB_FROM_TOKEN:CONSTANT or ATTRIB_RELATED_TO_API_CALL + The Identity service expects these attributes: + Attributes from token: user_id, the domain_id or project_id depending on + the scope, and the list of roles you have within that scope. + Attributes related to API call: Any parameters passed into the API call + are available, along with any filters specified in the query string. You + reference attributes of objects passed with an object.attribute syntax + (such as, user.domain_id). The target objects of an API are + also available using a target.object.attribute syntax. For + instance: + "identity:delete_user": [["role:admin", "domain_id:%(target.user.domain_id)s"]] + would ensure that Identity only deletes the user object in the same + domain as the provided token. +Every target object has an `id` and a `name` available as + `target.OBJECT.id` and `target.OBJECT.name`. Identity + retrieves other attributes from the database, and the attributes vary + between object types. The Identity service filters out some database + fields, such as user passwords. +List of object attributes: +role: + target.role.id + target.role.name + + user: + target.user.default_project_id + target.user.description + target.user.domain_id + target.user.enabled + target.user.id + target.user.name + + group: + target.group.description + target.group.domain_id + target.group.id + target.group.name + + domain: + target.domain.enabled + target.domain.id + target.domain.name + + project: + target.project.description + target.project.domain_id + target.project.enabled + target.project.id + target.project.name +The default policy.json file supplied provides a + somewhat basic example of API protection, and does not assume any + particular use of domains. Refer to + policy.v3cloudsample.json as an example of + multi-domain configuration installations where a cloud provider wants to + delegate administration of the contents of a domain to a particular admin + domain. This example policy file also shows the use of an admin_domain to + allow a cloud provider to enable cloud administrators to have wider access + across the APIs. +A clean installation could start with the standard policy file, to allow + creation of the admin_domain with the first users within it. You could + then obtain the domain_id of the admin domain, paste the ID into a + modified version of policy.v3cloudsample.json, and + then enable it as the main policy file. +