<?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="module001-ch007-keystone-arch">
  <title>Keystone Architecture</title>
  <!--<para>More Content To be Added ...</para>
  <section xml:id="module001-ch007-keystone-arch-concepts">
    <title>Identity Service Concepts</title> -->
    <para>The Identity service performs these
      functions:</para>
    <itemizedlist>
      <listitem>
          <para>User management: Tracks users and their
          permissions.</para>
      </listitem>
      <listitem>
          <para>Service catalog: Provides a catalog of available
          services with their API endpoints.</para>
      </listitem>
    </itemizedlist>
    <para>To understand the Identity Service, you must understand these concepts:</para>
    <variablelist wordsize="10">
      <varlistentry>
        <term><emphasis role="bold">User</emphasis></term>
        <listitem>
          <para>Digital representation of a person, system, or service
            who uses OpenStack cloud services. Identity authentication
            services will validate that incoming requests are being
            made by the user who claims to be making the call. Users
            have a login and may be assigned tokens to access
            resources. Users may be directly assigned to a particular
            tenant and behave as if they are contained in that
            tenant.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Credentials</emphasis></term>
        <listitem>
          <para>Data that is known only by a user that proves who they
            are. In the Identity Service, examples are:</para>
          <itemizedlist>
            <listitem>
              <para>Username and password</para>
            </listitem>
            <listitem>
              <para>Username and API key</para>
            </listitem>
            <listitem>
              <para>An authentication token provided by the Identity
                Service</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Authentication</emphasis></term>
        <listitem>
          <para>The act of confirming the identity of a user. The
            Identity Service confirms an incoming request by
            validating a set of credentials supplied by the user.
            These credentials are initially a username and password or
            a username and API key. In response to these credentials,
            the Identity Service issues the user an authentication
            token, which the user provides in subsequent
            requests.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <emphasis role="bold">Token</emphasis></term>
        <listitem>
          <para>An arbitrary bit of text that is used to access
            resources. Each token has a scope which describes which
            resources are accessible with it. A token may be revoked
            at anytime and is valid for a finite duration.</para>
          <para>While the Identity Service supports token-based
            authentication in this release, the intention is for it to
            support additional protocols in the future. The intent is
            for it to be an integration service foremost, and not
            aspire to be a full-fledged identity store and management
            solution.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Tenant</emphasis></term>
        <listitem>
          <para>A container used to group or isolate resources and/or
            identity objects. Depending on the service operator, a
            tenant may map to a customer, account, organization, or
            project.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <emphasis role="bold">Service</emphasis></term>
        <listitem>
          <para>An OpenStack service, such as Compute (Nova), Object
            Storage (Swift), or Image Service (Glance). Provides one
            or more endpoints through which users can access resources
            and perform operations.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Endpoint</emphasis></term>
        <listitem>
          <para>An network-accessible address, usually described by
            URL, from where you access a service. If using an
            extension for templates, you can create an endpoint
            template, which represents the templates of all the
            consumable services that are available across the
            regions.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Role</emphasis></term>
        <listitem>
          <para>A personality that a user assumes which enables them to
            perform a specific set of operations. A role includes a
            set of rights and privileges. A user assuming that role
            inherits those rights and privileges.</para>
          <para>In the Identity Service, a token that is issued to a
            user includes the list of roles that a user can assume.
            Services that are being called by that user determine how
            they interpret the set of roles a user has and which
            operations or resources each role grants access to.</para>
          <figure>
            <title>Keystone Authentication</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="figures/image19.png" contentwidth="4in" scale="50" width="4in"/>
              </imageobject>
            </mediaobject>
          </figure>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <emphasis role="bold">User management</emphasis></term>
        <listitem>
          <para>The main components of Identity user management
            are:</para>
          <itemizedlist>
            <listitem>
              <para>Users</para>
            </listitem>
            <listitem>
              <para>Tenants</para>
            </listitem>
            <listitem>
              <para>Roles</para>
            </listitem>
          </itemizedlist>
          <para>A user represents a human user, and has associated
            information such as username, password and email. This
            example creates a user named "alice":</para>
          <screen><prompt>$</prompt> <userinput>keystone user-create --name=alice --pass=mypassword123 --email=alice@example.com</userinput></screen>
          <para>A tenant can be a project, group, or organization.
            Whenever you make requests to OpenStack services, you must
            specify a tenant. For example, if you query the Compute
            service for a list of running instances, you get a list of
            all running instances for the specified tenant. This
            example creates a tenant named "acme":</para>
          <screen><prompt>$</prompt> <userinput>keystone tenant-create --name=acme</userinput></screen>
          <para>A role captures what operations a user is permitted to
            perform in a given tenant. This example creates a role
            named "compute-user":</para>
          <screen><prompt>$</prompt> <userinput>keystone role-create --name=compute-user</userinput></screen>
          <para>The Identity service associates a user with a tenant
            and a role. To continue with our previous examples, we may
            assign the "alice" user the "compute-user" role in
            the "acme" tenant:</para>
          <screen><prompt>$</prompt> <userinput>keystone user-list</userinput></screen>
          <screen><prompt>$</prompt> <userinput>keystone user-role-add --user=892585 --role=9a764e --tenant-id=6b8fd2</userinput></screen>
          <para>A user can be assigned different roles in different
            tenants. For example, Alice may also have the "admin" role
            in the "Cyberdyne" tenant. A user can also be assigned
            multiple roles in the same tenant.</para>
          <para>The
              <filename>/etc/[SERVICE_CODENAME]/policy.json</filename>
            file controls what users are allowed to do for a given
            service. For example,
              <filename>/etc/nova/policy.json</filename> specifies the
            access policy for the Compute service,
              <filename>/etc/glance/policy.json</filename> specifies
            the access policy for the Image Service, and
              <filename>/etc/keystone/policy.json</filename> specifies
            the access policy for the Identity service.</para>
          <para>The default policy.json files in the Compute,
            Identity, and Image Service recognize only the admin role:
            all operations that do not require the admin role will be
            accessible by any user that has any role in a
            tenant.</para>
          <para>If you wish to restrict users from performing
            operations in the Compute service, you need to
            create a role in the Identity service and then modify
              <filename>/etc/nova/policy.json</filename> so that this
            role is required for Compute operations.</para>
          <para>For example, this line in
              <filename>/etc/nova/policy.json</filename> specifies
            that there are no restrictions on which users can create
            volumes: if the user has any role in a tenant, they will
            be able to create volumes in that tenant.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">Service
          Management</emphasis></term>
        <listitem>
          <para>The Identity Service provides the following service
            management functions:</para>
          <itemizedlist>
            <listitem>
              <para>Services</para>
            </listitem>
            <listitem>
              <para>Endpoints</para>
            </listitem>
          </itemizedlist>
          <para>The Identity Service also maintains a user that
            corresponds to each service, such as a user named nova,
            (for the Compute service) and a special service tenant,
            which is called service.</para>
          <para>The commands for creating services and endpoints are
            described in a later section.</para>
        </listitem>
      </varlistentry>
    </variablelist>
 <!-- </section>-->
</chapter>