openstack-manuals/doc/install-guide/section_keystone-users.xml

<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         version="5.0"
         xml:id="keystone-users" os="rhel;centos;fedora;opensuse;sles;ubuntu">
  <title>Define users, tenants, and roles</title>

  <para>After you install the Identity Service, set up
  <glossterm baseform="user">users</glossterm>,
  <glossterm baseform="tenant">tenants</glossterm>, and
  <glossterm baseform="role">roles</glossterm> to authenticate
  against. These are used to allow access to
  services and <glossterm baseform="endpoint">endpoints</glossterm>, described
  in the next section.</para>

  <para>Typically, you would indicate a user and password to
    authenticate with the Identity Service. At this point, however, you
    have not created any users, so you have to use the authorization
    token created in an earlier step, see <xref linkend="keystone-install"/>
    for further details. You can pass this with the
      <option>--os-token</option> option to the
      <command>keystone</command> command or set the
      <envar>OS_SERVICE_TOKEN</envar> environment variable. Set
      <envar>OS_SERVICE_TOKEN</envar>, as well as
      <envar>OS_SERVICE_ENDPOINT</envar> to specify where the Identity
    Service is running. Replace
        <userinput><replaceable>ADMIN_TOKEN</replaceable></userinput>
    with your authorization token.</para>

  <screen><prompt>$</prompt> <userinput>export OS_SERVICE_TOKEN=<replaceable>ADMIN_TOKEN</replaceable></userinput>
<prompt>$</prompt> <userinput>export OS_SERVICE_ENDPOINT=http://controller:35357/v2.0</userinput></screen>

  <procedure>
    <title>Create an administrative user</title>
    <para>
      Follow these steps to create an administrative user, role, and
      tenant. You will use this account for administrative interaction
      with the OpenStack cloud.
    </para>
    <para>
      By default, the Identity Service creates a special
      <literal>_member_</literal> role. The OpenStack dashboard
      automatically grants access to users with this role. You will
      give the <literal>admin</literal> user access to this role in
      addition to the <literal>admin</literal> role.
    </para>
    <note>
      <para>
        Any role that you create must map to roles specified in the
        <filename>policy.json</filename> file included with each OpenStack
        service. The default policy file for most services grants
        administrative access to the <literal>admin</literal> role.
      </para>
    </note>
    <step>
      <para>
        Create the <literal>admin</literal> user:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone user-create --name=admin --pass=<replaceable>ADMIN_PASS</replaceable> --email=<replaceable>ADMIN_EMAIL</replaceable></userinput></screen>
      <para>
        Replace <replaceable>ADMIN_PASS</replaceable> with a secure password
        and replace <replaceable>ADMIN_EMAIL</replaceable> with an email
        address to associate with the account.
      </para>
    </step>
    <step>
      <para>
        Create the <literal>admin</literal> role:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone role-create --name=admin</userinput></screen>
    </step>
    <step>
      <para>
        Create the <literal>admin</literal> tenant:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone tenant-create --name=admin --description="Admin Tenant"</userinput></screen>
    </step>
    <step>
      <para>
        You must now link the <literal>admin</literal> user,
        <literal>admin</literal> role, and <literal>admin</literal> tenant
        together using the <option>user-role-add</option> option:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone user-role-add --user=admin --tenant=admin --role=admin</userinput></screen>
    </step>
    <step>
      <para>
        Link the <literal>admin</literal> user,
        <literal>_member_</literal> role, and <literal>admin</literal> tenant:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone user-role-add --user=admin --role=_member_ --tenant=admin</userinput></screen>
    </step>
  </procedure>
  <procedure>
    <title>Create a normal user</title>
    <para>
      Follow these steps to create a normal user and tenant, and link
      them to the special <literal>_member_</literal> role. You will
      use this account for daily non-administrative interaction with
      the OpenStack cloud. You can also repeat this procedure to create
      additional cloud users with different usernames and passwords.
      Skip the tenant creation step when creating these users.
    </para>
    <step>
      <para>
        Create the <literal>demo</literal> user:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone user-create --name=demo --pass=<replaceable>DEMO_PASS</replaceable> --email=<replaceable>DEMO_EMAIL</replaceable></userinput></screen>
      <para>
        Replace <replaceable>DEMO_PASS</replaceable> with a secure password
        and replace <replaceable>DEMO_EMAIL</replaceable> with an email
        address to associate with the account.
      </para>
    </step>
    <step>
      <para>
        Create the <literal>demo</literal> tenant:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone tenant-create --name=demo --description="Demo Tenant"</userinput></screen>
      <note>
        <para>
          Do not repeat this step when adding additional users.
        </para>
      </note>
    </step>
    <step>
      <para>
        Link the <literal>demo</literal> user, <literal>_member_</literal> role,
        and <literal>demo</literal> tenant:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone user-role-add --user=demo --role=_member_ --tenant=demo</userinput></screen>
    </step>
  </procedure>
  <procedure>
    <title>Create a <literal>service</literal> tenant</title>
    <para>
      OpenStack services also require a username, tenant, and role to access
      other OpenStack services. In a basic installation, OpenStack services
      typically share a single tenant named <literal>service</literal>.
    </para>
    <para>
      You will create additional usernames and roles under this tenant as you
      install and configure each service.
    </para>
    <step>
      <para>
        Create the <literal>service</literal> tenant:
      </para>
      <screen><prompt>$</prompt> <userinput>keystone tenant-create --name=service --description="Service Tenant"</userinput></screen>
    </step>
  </procedure>
</section>