273 lines
14 KiB
XML
273 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="ch-identity-mgmt-config">
|
|
<title>Identity management</title>
|
|
<para>OpenStack Identity, code-named keystone, is the
|
|
default identity management system for OpenStack. After you
|
|
install Identity, you configure it through the
|
|
<filename>etc/keystone.conf</filename> configuration file and,
|
|
possibly, a separate logging configuration file. You initialize
|
|
data into Identity by using the
|
|
<command>keystone</command> command-line client.</para>
|
|
<section xml:id="keystone-admin-concepts">
|
|
<title>Identity concepts</title>
|
|
<xi:include
|
|
href="../common/section_keystone-concepts-user-management.xml"/>
|
|
<xi:include
|
|
href="../common/section_keystone-concepts-service-management.xml"/>
|
|
<xi:include
|
|
href="../common/section_keystone-concepts-group-management.xml"/>
|
|
</section>
|
|
<xi:include href="../common/section_keystone_certificates-for-pki.xml"/>
|
|
<xi:include href="../common/section_keystone-ssl-config.xml"/>
|
|
<xi:include href="../common/section_keystone-external-auth.xml"/>
|
|
<xi:include href="../common/section_keystone_config_ldap.xml"/>
|
|
<xi:include href="identity/section_keystone-token-binding.xml"/>
|
|
<xi:include href="identity/section_keystone-trusts.xml"/>
|
|
<xi:include href="identity/section_caching-layer.xml"/>
|
|
<section xml:id="user-crud">
|
|
<title>User CRUD</title>
|
|
<para>Identity provides a user CRUD (Create, Read, Update, and Delete)
|
|
filter that can be added to the <literal>public_api</literal> pipeline.
|
|
The user CRUD filter enables users to use a HTTP PATCH to change their
|
|
own password. To enable this extension you should define a
|
|
<literal>user_crud_extension</literal> filter, insert it after
|
|
the <literal>*_body</literal> middleware and before the
|
|
<literal>public_service</literal> application in the
|
|
<literal>public_api</literal> WSGI pipeline in
|
|
<filename>keystone-paste.ini</filename>. For example:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[filter:user_crud_extension]
|
|
paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory
|
|
|
|
[pipeline:public_api]
|
|
pipeline = sizelimit url_normalize request_id build_auth_context token_auth admin_token_auth json_body ec2_extension user_crud_extension public_service</programlisting>
|
|
<para>Each user can then change their own password with a HTTP PATCH:</para>
|
|
<screen><prompt>$</prompt> <userinput>curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<replaceable>USERID</replaceable> -H "Content-type: application/json" \
|
|
-H "X_Auth_Token: <replaceable>AUTHTOKENID</replaceable>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}'</userinput></screen>
|
|
<para>In addition to changing their password, all current
|
|
tokens for the user are invalidated.</para>
|
|
<note><para>Only use a KVS back end for tokens when testing.</para></note>
|
|
</section>
|
|
<section xml:id="keystone-logging">
|
|
<title>Logging</title>
|
|
<para>You configure logging externally to the rest of Identity. The name of
|
|
the file specifying the logging configuration is set using the
|
|
<literal>log_config</literal> option in the <literal>[DEFAULT]</literal>
|
|
section of the <filename>keystone.conf</filename> file. To route logging
|
|
through syslog, set <literal>use_syslog=true</literal> in the
|
|
<literal>[DEFAULT]</literal> section.</para>
|
|
<para>A sample logging configuration file is available with the project in
|
|
<filename>etc/logging.conf.sample</filename>. Like
|
|
other OpenStack projects, Identity uses the Python
|
|
logging module, which provides extensive configuration options
|
|
that let you define the output levels and formats.</para>
|
|
</section>
|
|
<section xml:id="running-keystone">
|
|
<title>Start the Identity services</title>
|
|
<para>To start the services for Identity, run the
|
|
following command:</para>
|
|
<screen><prompt>$</prompt> <userinput>keystone-all</userinput></screen>
|
|
<para>This command starts two wsgi.Server instances configured by
|
|
the <filename>keystone.conf</filename> file as described
|
|
previously. One of these wsgi servers is
|
|
<literal>admin</literal> (the administration API) and the
|
|
other is <literal>main</literal> (the primary/public API
|
|
interface). Both run in a single process.</para>
|
|
</section>
|
|
<section xml:id="example-usage">
|
|
<title>Example usage</title>
|
|
<para>The <literal>keystone</literal> client is set up to expect
|
|
commands in the general form of <literal>keystone</literal>
|
|
<literal>command</literal>
|
|
<literal>argument</literal>, followed by flag-like keyword
|
|
arguments to provide additional (often optional) information.
|
|
For example, the command <literal>user-list</literal> and
|
|
<literal>tenant-create</literal> can be invoked as
|
|
follows:</para>
|
|
<programlisting language="bash"><?db-font-size 65%?># Using token auth env variables
|
|
export OS_SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/
|
|
export OS_SERVICE_TOKEN=secrete_token
|
|
keystone user-list
|
|
keystone tenant-create --name demo
|
|
|
|
# Using token auth flags
|
|
keystone --os-token secrete --os-endpoint http://127.0.0.1:5000/v2.0/ user-list
|
|
keystone --os-token secrete --os-endpoint http://127.0.0.1:5000/v2.0/ tenant-create --name=demo
|
|
|
|
# Using user + password + project_name env variables
|
|
export OS_USERNAME=admin
|
|
export OS_PASSWORD=secrete
|
|
export OS_PROJECT_NAME=admin
|
|
openstack user list
|
|
openstack project create demo
|
|
|
|
# Using user + password + project-name flags
|
|
openstack --os-username admin --os-password secrete --os-project-name admin user list
|
|
openstack --os-username admin --os-password secrete --os-project-name admin project create demo</programlisting>
|
|
</section>
|
|
<section xml:id="auth-token-middleware-with-username-and-password">
|
|
<title>Authentication middleware with user name and
|
|
password</title>
|
|
<para>You can also configure Identity authentication
|
|
middleware using the <option>admin_user</option> and
|
|
<option>admin_password</option> options.</para>
|
|
<note><para>The <option>admin_token</option> option is deprecated,
|
|
and no longer used for configuring auth_token middleware.</para></note>
|
|
<para>For services that have a separate paste-deploy .ini file,
|
|
you can configure the authentication middleware in the
|
|
<literal>[keystone_authtoken]</literal> section of the main
|
|
configuration file, such as <filename>nova.conf</filename>. In
|
|
Compute, for example, you can remove the middleware parameters
|
|
from <filename>api-paste.ini</filename>, as follows:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[filter:authtoken]
|
|
paste.filter_factory = keystonemiddleware.auth_token:filter_factory</programlisting>
|
|
<note><para>Prior to the Juno release, the auth_token middleware was in
|
|
python-keystoneclient. The filter_factory must be set to
|
|
<literal>keystoneclient.middleware.auth_token:filter_factory</literal>
|
|
in those releases.
|
|
</para></note>
|
|
<para>And set the following values in
|
|
<filename>nova.conf</filename> as follows:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[DEFAULT]
|
|
...
|
|
auth_strategy=keystone
|
|
|
|
[keystone_authtoken]
|
|
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
|
|
identity_uri = http://<replaceable>controller</replaceable>:35357
|
|
admin_user = admin
|
|
admin_password = SuperSekretPassword
|
|
admin_tenant_name = service</programlisting>
|
|
<note>
|
|
<para>The middleware parameters in the paste config take
|
|
priority. You must remove them to use the values in the
|
|
[keystone_authtoken] section.</para>
|
|
</note>
|
|
<note>
|
|
<para>Comment out any <literal>auth_host</literal>,
|
|
<literal>auth_port</literal>, and
|
|
<literal>auth_protocol</literal> options because the
|
|
<literal>identity_uri</literal> option replaces them.</para>
|
|
</note>
|
|
<para>This sample paste config filter makes use of the
|
|
<option>admin_user</option> and
|
|
<option>admin_password</option> options:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[filter:authtoken]
|
|
paste.filter_factory = keystonemiddleware.auth_token:filter_factory
|
|
auth_uri = http://<replaceable>controller</replaceable>:5000/v2.0
|
|
identity_uri = http://<replaceable>controller</replaceable>:35357
|
|
auth_token = 012345SECRET99TOKEN012345
|
|
admin_user = admin
|
|
admin_password = keystone123</programlisting>
|
|
<note>
|
|
<para>Using this option requires an admin tenant/role
|
|
relationship. The admin user is granted access to the admin
|
|
role on the admin tenant.</para>
|
|
</note>
|
|
<note>
|
|
<para>Comment out any <literal>auth_host</literal>,
|
|
<literal>auth_port</literal>, and
|
|
<literal>auth_protocol</literal> options because the
|
|
<literal>identity_uri</literal> option replaces them.</para>
|
|
</note>
|
|
<note><para>Prior to the Juno release, the auth_token middleware was in
|
|
python-keystoneclient. The filter_factory must be set to
|
|
<literal>keystoneclient.middleware.auth_token:filter_factory</literal>
|
|
in those releases.
|
|
</para></note>
|
|
</section>
|
|
<section xml:id="identity-service-api-protection-with-role-based-access-control">
|
|
<title>Identity API protection with role-based access control (RBAC)
|
|
</title>
|
|
<para>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, <filename>keystone.conf</filename>. Typically this
|
|
file is named <filename>policy.json</filename>, and it contains the rules
|
|
for which roles have access to certain actions in defined services.</para>
|
|
<para>Each Identity API v3 call has a line in the policy file that dictates which
|
|
level of governance of access applies.</para>
|
|
<programlisting language="ini"><replaceable>API_NAME</replaceable>: <replaceable>RULE_STATEMENT</replaceable> or <replaceable>MATCH_STATEMENT</replaceable></programlisting>
|
|
<para>Where:</para>
|
|
<para><code><replaceable>RULE_STATEMENT</replaceable></code> can contain <code><replaceable>RULE_STATEMENT</replaceable></code> or <code><replaceable>MATCH_STATEMENT</replaceable></code>.</para>
|
|
<para><code><replaceable>MATCH_STATEMENT</replaceable></code> 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:</para>
|
|
<programlisting language="ini">"identity:create_user": [["role:admin", "domain_id:%(user.domain_id)s"]]</programlisting>
|
|
<para>Indicates that to create a user, you must have the admin role in your token and
|
|
the <literal>domain_id</literal> in your token (which implies this must be a domain-scoped token)
|
|
must match the <literal>domain_id</literal> 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.</para>
|
|
<para>Each component of a match statement uses this format:</para>
|
|
<programlisting language="ini"><replaceable>ATTRIB_FROM_TOKEN</replaceable>:<replaceable>CONSTANT</replaceable> or <replaceable>ATTRIB_RELATED_TO_API_CALL</replaceable></programlisting>
|
|
<para>The Identity service expects these attributes:</para>
|
|
<para>Attributes from token: <literal>user_id</literal>, the <literal>domain_id</literal> or <literal>project_id</literal> depending on
|
|
the scope, and the list of roles you have within that scope.</para>
|
|
<para>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, <literal>user.domain_id</literal>). The target objects of an API are
|
|
also available using a target.object.attribute syntax. For
|
|
instance:</para>
|
|
<programlisting language="ini">"identity:delete_user": [["role:admin", "domain_id:%(target.user.domain_id)s"]]</programlisting>
|
|
<para>would ensure that Identity only deletes the user object in the same
|
|
domain as the provided token.</para>
|
|
<para>Every target object has an `id` and a `name` available as
|
|
`target.<replaceable>OBJECT</replaceable>.id` and `target.<replaceable>OBJECT</replaceable>.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.</para>
|
|
<para>List of object attributes:</para>
|
|
<programlisting language="ini">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</programlisting>
|
|
<para>The default <filename>policy.json</filename> file supplied provides a
|
|
somewhat basic example of API protection, and does not assume any
|
|
particular use of domains. Refer to
|
|
<filename>policy.v3cloudsample.json</filename> 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.</para>
|
|
<para>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 <filename>policy.v3cloudsample.json</filename>, and
|
|
then enable it as the main policy file.</para>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<xi:include href="../common/section_identity-troubleshooting.xml"/>
|
|
</chapter>
|