openstack/keystone
Code Issues Proposed changes

Merge "Move bootstrapping documentation to admin-guide"

Browse Source
This commit is contained in:
Jenkins 2017-07-16 10:33:49 +00:00 committed by Gerrit Code Review
commit 33b0ec1397
3 changed files with 127 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
doc/source/admin/identity-bootstrap.rst Normal file
View File

@ -0,0 +1,126 @@
======================
Bootstrapping Identity
======================
After keystone is deployed and configured, it must be pre-populated with some
initial data before it can be used. This process is known as bootstrapping and
it typically involves creating the system's first user, project, domain,
service, and endpoint, among other things. The goal of bootstrapping is to put
enough information into the system such that it can function solely through the
API using normal authentication flows. After the first user is created, which
must be an administrator, you can use that account to interact with keystone
via the API.
Keystone provides two separate ways to bootstrap a deployment. The first is
with the ``keystone-manage bootstrap`` command. This is the perferred and
recommended way to boostrap new installations. The second, and original way of
bootstrapping involves configuring a secret and deploying special middleware in
front of the identity service. The secret is known as the ``ADMIN_TOKEN``. Any
requests made to the identity API with the ``ADMIN_TOKEN`` will completely
bypass authentication allowing access to the entire API.
Using the CLI
=============
The process requires access to an environment with keystone binaries
installed, typically on the service host.
The ``keystone-manage bootstrap`` command will create a user, project and role,
and will assign the newly created role to the newly created user on the newly
created project. By default, the names of these new resources will be called
``admin``.
The defaults may be overridden by calling ``--bootstrap-username``,
``--bootstrap-project-name`` and ``--bootstrap-role-name``. Each of these have
an environment variable equivalent: ``OS_BOOTSTRAP_USERNAME``,
``OS_BOOTSTRAP_PROJECT_NAME`` and ``OS_BOOTSTRAP_ROLE_NAME``.
A user password must also be supplied. This can be passed in as either
``--bootstrap-password``, or set as an environment variable using
``OS_BOOTSTRAP_PASSWORD``.
Optionally, if specified by ``--bootstrap-public-url``,
``--bootstrap-admin-url`` and/or ``--bootstrap-internal-url`` or the equivalent
environment variables, the command will create an identity service with the
specified endpoint information. You may also configure the
``--bootstrap-region-id`` and ``--bootstrap-service-name`` for the endpoints to
your deployment's requirements.
.. NOTE::
We strongly recommend that you configure the identity service and its
endpoints while bootstrapping keystone.
Minimally, keystone can be bootstrapped with:
.. code-block:: bash
$ keystone-manage bootstrap --bootstrap-password s3cr3t
Verbosely, keystone can be bootstrapped with:
.. code-block:: bash
$ keystone-manage bootstrap \
--bootstrap-password s3cr3t \
--bootstrap-username admin \
--bootstrap-project-name admin \
--bootstrap-role-name admin \
--bootstrap-service-name keystone \
--bootstrap-region-id RegionOne \
--bootstrap-admin-url http://localhost:35357 \
--bootstrap-public-url http://localhost:5000 \
--bootstrap-internal-url http://localhost:5000
This will create an ``admin`` user with the ``admin`` role on the ``admin``
project. The user will have the password specified in the command. Note that
both the user and the project will be created in the ``default`` domain. By not
creating an endpoint in the catalog users will need to provide endpoint
overrides to perform additional identity operations.
By creating an ``admin`` user and an identity endpoint you may
authenticate to keystone and perform identity operations like creating
additional services and endpoints using the ``admin`` user. This will preclude
the need to ever use or configure the ``admin_token`` (described below). It is
also, by design, more secure.
To test a proper configuration, a user can use OpenStackClient CLI:
.. code-block:: bash
$ openstack project list --os-username admin --os-project-name admin \
--os-user-domain-id default --os-project-domain-id default \
--os-identity-api-version 3 --os-auth-url http://localhost:5000 \
--os-password s3cr3t
Using a shared secret
=====================
.. NOTE::
We strongly recommended that you configure the identity service with the
``keystone-manage bootstrap`` command and not the ``ADMIN_TOKEN``. The
``ADMIN_TOKEN`` can leave your deployment vulnerable by exposing
administrator functionality through the API based solely on a single
secret.
Before you can use the identity API, you need to configure keystone with a
shared secret. Requests made with this secret will bypass authentication and
grant administrative access to the identity API. The following configuration
snippet shows the shared secret as being ``ADMIN``:
.. code-block:: bash
[DEFAULT]
admin_token = ADMIN
You can use the shared secret, or ``admin_token``, to make API request to
keystone that bootstrap the rest of the deployment. You must create a project,
user, and role in order to use normal user authentication through the API.
The ``admin_token`` does not represent a user or explicit authorization of any
kind. It is imperative that you disable the ``AdminTokenAuthMiddleware`` from
your paste application pipelines after bootstrapping, especially in production
deployments. Failure to remove this functionality exposes an additional attack
vector and security risk.

1
doc/source/admin/identity-management.rst
View File

@ -15,6 +15,7 @@ command-line client.
:maxdepth: 1 :maxdepth: 1
identity-concepts.rst identity-concepts.rst
identity-bootstrap.rst
identity-certificates-for-pki.rst identity-certificates-for-pki.rst
identity-domain-specific-config.rst identity-domain-specific-config.rst
identity-external-authentication.rst identity-external-authentication.rst

111
doc/source/configuration.rst
View File

@ -106,117 +106,6 @@ is not an absolute path, then keystone looks for it in the same directories as
above. If not specified, WSGI pipeline definitions are loaded from the primary above. If not specified, WSGI pipeline definitions are loaded from the primary
configuration file. configuration file.
Bootstrapping Keystone with ``keystone-manage bootstrap``
=========================================================
Setting up projects, users, and roles
-------------------------------------
The ``keystone-manage bootstrap`` command will create a user, project and role,
and will assign the newly created role to the newly created user on the newly
created project. By default, the names of these new resources will be called
``admin``.
The defaults may be overridden by calling ``--bootstrap-username``,
``--bootstrap-project-name`` and ``--bootstrap-role-name``. Each of these have
an environment variable equivalent: ``OS_BOOTSTRAP_USERNAME``,
``OS_BOOTSTRAP_PROJECT_NAME`` and ``OS_BOOTSTRAP_ROLE_NAME``.
A user password must also be supplied. This can be passed in as either
``--bootstrap-password``, or set as an environment variable using
``OS_BOOTSTRAP_PASSWORD``.
Optionally, if specified by ``--bootstrap-public-url``,
``--bootstrap-admin-url`` and/or ``--bootstrap-internal-url`` or the equivalent
environment variables, the command will create an identity service with the
specified endpoint information. You may also configure the
``--bootstrap-region-id`` and ``--bootstrap-service-name`` for the endpoints to
your deployment's requirements.
.. NOTE::
It is strongly encouraged to configure the identity service and its
endpoints while bootstrapping keystone.
Minimally, keystone can be bootstrapped with:
.. code-block:: bash
$ keystone-manage bootstrap --bootstrap-password s3cr3t
Verbosely, keystone can be bootstrapped with:
.. code-block:: bash
$ keystone-manage bootstrap \
--bootstrap-password s3cr3t \
--bootstrap-username admin \
--bootstrap-project-name admin \
--bootstrap-role-name admin \
--bootstrap-service-name keystone \
--bootstrap-region-id RegionOne \
--bootstrap-admin-url http://localhost:35357 \
--bootstrap-public-url http://localhost:5000 \
--bootstrap-internal-url http://localhost:5000
This will create an ``admin`` user with the ``admin`` role on the ``admin``
project. The user will have the password specified in the command. Note that
both the user and the project will be created in the ``default`` domain. By not
creating an endpoint in the catalog users will need to provide endpoint
overrides to perform additional identity operations.
By creating an ``admin`` user and an identity endpoint deployers may
authenticate to keystone and perform identity operations like creating
additional services and endpoints using that ``admin`` user. This will preclude
the need to ever use or configure the ``admin_token`` (described below).
To test a proper configuration, a user can use OpenStackClient CLI:
.. code-block:: bash
$ openstack project list --os-username admin --os-project-name admin \
--os-user-domain-id default --os-project-domain-id default \
--os-identity-api-version 3 --os-auth-url http://localhost:5000 \
--os-password s3cr3t
Bootstrapping Keystone with ``ADMIN_TOKEN``
===========================================
.. NOTE::
It is strongly recommended to configure the identity service with the
``keystone-manage bootstrap`` command and not the ``ADMIN_TOKEN``.
Admin Token
-----------
For a default installation of Keystone, before you can use the REST API, you
need to define an authorization token. This is configured in ``keystone.conf``
file under the section ``[DEFAULT]``. In the sample file provided with the
Keystone project, the line defining this token is::
[DEFAULT]
admin_token = ADMIN
A "shared secret" that can be used to bootstrap Keystone. This token does not
represent a user, and carries no explicit authorization.
To disable in production (highly recommended), remove
``AdminTokenAuthMiddleware`` from your paste application pipelines (for example,
in ``keystone-paste.ini``)
Setting up projects, users, and roles
-------------------------------------
You need to minimally define a project, user, and role to link the project and
user as the most basic set of details to get other services authenticating
and authorizing with Keystone.
You will also want to create service users for nova, glance, swift, etc. to
be able to use to authenticate users against Keystone. The ``auth_token``
middleware supports using either the shared secret described above as
`admin_token` or users for each service.
Setting up other OpenStack Services Setting up other OpenStack Services
=================================== ===================================