233 lines
11 KiB
XML
233 lines
11 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">
|
|
<?dbhtml stop-chunking?>
|
|
<title>Identity management</title>
|
|
<para>The OpenStack Identity Service, code-named Keystone, is the
|
|
default identity management system for OpenStack. After you
|
|
install the Identity Service, you configure it through the
|
|
<filename>etc/keystone.conf</filename> configuration file and,
|
|
possibly, a separate logging configuration file. You initialize
|
|
data into the Identity Service by using the
|
|
<command>keystone</command> command-line client.</para>
|
|
<section xml:id="keystone-admin-concepts">
|
|
<title>Identity Service 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"/>
|
|
<xi:include
|
|
href="../common/section_keystone-concepts-domain-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"/>
|
|
<section xml:id="user-crud">
|
|
<title>User CRUD</title>
|
|
<para>The Identity Service 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
|
|
<literal>user_crud_extension</literal> filter, insert it after
|
|
the <literal>*_body</literal> middleware and before the
|
|
<literal>public_service</literal> application in the
|
|
public_api WSGI pipeline in <filename>keystone.conf</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 = stats_monitoring url_normalize token_auth admin_token_auth xml_body json_body debug 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/<userid> -H "Content-type: application/json" \
|
|
-H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}'</userinput></screen>
|
|
<para>In addition to changing their password, all of the user's current
|
|
tokens are deleted (if the back-end is KVS or sql).</para>
|
|
<note><para>Only use a KVS backend for tokens when testing.</para></note>
|
|
</section>
|
|
<section xml:id="keystone-logging">
|
|
<title>Logging</title>
|
|
<para>You configure logging externally to the rest of the Identity
|
|
Service. The file specifying the logging configuration is in the
|
|
<literal>[DEFAULT]</literal> section of the
|
|
<filename>keystone.conf</filename> file under
|
|
<literal>log_config</literal>. To route logging through
|
|
syslog, set <literal>use_syslog=true</literal> option in the
|
|
<literal>[DEFAULT]</literal> section.</para>
|
|
<para>A sample logging file is available with the project in the
|
|
<filename>etc/logging.conf.sample</filename> directory. Like
|
|
other OpenStack projects, the Identity Service uses the Python
|
|
logging module, which includes extensive configuration options
|
|
that let you define the output levels and formats.</para>
|
|
<para>Review the <filename>etc/keystone.conf</filename> sample
|
|
configuration files that are distributed with the Identity
|
|
Service. For example, each server application has its own
|
|
configuration file.</para>
|
|
<para>For services that have separate paste-deploy
|
|
<filename>.ini</filename> files, you can configure
|
|
<literal>auth_token</literal> middleware in the
|
|
<literal>[keystone_authtoken]</literal> section in the main
|
|
configuration file, such as <filename>nova.conf</filename>. For
|
|
example in Compute, 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 =
|
|
keystoneclient.middleware.auth_token:filter_factory</programlisting>
|
|
<para>Set these values in the <filename>nova.conf</filename>
|
|
file:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[DEFAULT]
|
|
...
|
|
auth_strategy=keystone
|
|
|
|
[keystone_authtoken]
|
|
auth_host = 127.0.0.1
|
|
auth_port = 35357
|
|
auth_protocol = http
|
|
auth_uri = http://127.0.0.1:5000/
|
|
admin_user = admin
|
|
admin_password = SuperSekretPassword
|
|
admin_tenant_name = service</programlisting>
|
|
<note>
|
|
<para>Middleware parameters in paste config take priority. You
|
|
must remove them to use values in the
|
|
<literal>[keystone_authtoken]</literal> section.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="monitoring">
|
|
<title>Monitoring</title>
|
|
<para>The Identity Service provides some basic request/response
|
|
monitoring statistics out of the box.</para>
|
|
<para>Enable data collection by defining a
|
|
<literal>stats_monitoring</literal> filter and including it at
|
|
the beginning of any desired WSGI pipelines:</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[filter:stats_monitoring]
|
|
paste.filter_factory = keystone.contrib.stats:StatsMiddleware.factory
|
|
|
|
[pipeline:public_api]
|
|
pipeline = stats_monitoring [...] public_service</programlisting>
|
|
<para>Enable the reporting of collected data by defining a
|
|
<literal>stats_reporting</literal> filter and including it
|
|
near the end of your <literal>admin_api</literal> WSGI pipeline
|
|
(After <literal>*_body</literal> middleware and before
|
|
<literal>*_extension</literal> filters is recommended):</para>
|
|
<programlisting language="ini"><?db-font-size 75%?>[filter:stats_reporting]
|
|
paste.filter_factory = keystone.contrib.stats:StatsExtension.factory
|
|
|
|
[pipeline:admin_api]
|
|
pipeline = [...] json_body stats_reporting ec2_extension [...] admin_service</programlisting>
|
|
<para>Query the admin API for statistics using:</para>
|
|
<screen><prompt>$</prompt> <userinput>curl -H 'X-Auth-Token: ADMIN' http://localhost:35357/v2.0/OS-STATS/stats</userinput></screen>
|
|
<para>Reset collected data using:</para>
|
|
<screen><prompt>$</prompt> <userinput>curl -H 'X-Auth-Token: ADMIN' -X DELETE \
|
|
http://localhost:35357/v2.0/OS-STATS/stats</userinput></screen>
|
|
</section>
|
|
<section xml:id="running-keystone">
|
|
<title>Start the Identity Service</title>
|
|
<para>To start the services for the Identity Service, 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 SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/
|
|
export SERVICE_TOKEN=secrete_token
|
|
keystone user-list
|
|
keystone tenant-create --name=demo
|
|
|
|
# Using token auth flags
|
|
keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ user-list
|
|
keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ tenant-create --name=demo
|
|
|
|
# Using user + password + tenant_name env variables
|
|
export OS_USERNAME=admin
|
|
export OS_PASSWORD=secrete
|
|
export OS_TENANT_NAME=admin
|
|
keystone user-list
|
|
keystone tenant-create --name=demo
|
|
|
|
# Using user + password + tenant_name flags
|
|
keystone --username=admin --password=secrete --tenant_name=admin user-list
|
|
keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=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 the Identity Service authentication
|
|
middleware using the <option>admin_user</option> and
|
|
<option>admin_password</option> options. When using the
|
|
<option>admin_user</option> and
|
|
<option>admin_password</option> options the
|
|
<option>admin_token</option> parameter is optional. If
|
|
<option>admin_token</option> is specified, it is used only if
|
|
the specified token is still valid.</para>
|
|
<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 =
|
|
keystoneclient.middleware.auth_token:filter_factory</programlisting>
|
|
<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_host = 127.0.0.1
|
|
auth_port = 35357
|
|
auth_protocol = http
|
|
auth_uri = http://127.0.0.1:5000/
|
|
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>
|
|
<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 = keystoneclient.middleware.auth_token:filter_factory
|
|
service_port = 5000
|
|
service_host = 127.0.0.1
|
|
auth_port = 35357
|
|
auth_host = 127.0.0.1
|
|
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>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<xi:include href="../common/section_identity-troubleshooting.xml"/>
|
|
</chapter>
|