openstack-manuals/doc/admin-guide-cloud/ch_identity_mgmt.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 &quot;Content-type: application/json&quot;  \
  -H &quot;X_Auth_Token: <replaceable>AUTHTOKENID</replaceable>&quot; -d '{&quot;user&quot;: {&quot;password&quot;: &quot;ABCD&quot;, &quot;original_password&quot;: &quot;DCBA&quot;}}'</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>.</para>
    <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>
  </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>