From a393792028b6d1be883c6856d2c3f1ead5ed4bbf Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Sat, 15 Jul 2017 20:03:29 +0000 Subject: [PATCH] Move bootstrapping documentation to admin-guide The operator documentation had two sections that described bootstrapping keystone. This is better suited for the admin-guide and this commit moves it there. Change-Id: Ibca2bc3e439ca6e26d8e4ead13ed101fd9010f12 --- doc/source/admin/identity-bootstrap.rst | 126 +++++++++++++++++++++++ doc/source/admin/identity-management.rst | 1 + doc/source/configuration.rst | 111 -------------------- 3 files changed, 127 insertions(+), 111 deletions(-) create mode 100644 doc/source/admin/identity-bootstrap.rst diff --git a/doc/source/admin/identity-bootstrap.rst b/doc/source/admin/identity-bootstrap.rst new file mode 100644 index 0000000000..22f9c05e03 --- /dev/null +++ b/doc/source/admin/identity-bootstrap.rst @@ -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. diff --git a/doc/source/admin/identity-management.rst b/doc/source/admin/identity-management.rst index 3d51b77aea..20685a21d2 100644 --- a/doc/source/admin/identity-management.rst +++ b/doc/source/admin/identity-management.rst @@ -15,6 +15,7 @@ command-line client. :maxdepth: 1 identity-concepts.rst + identity-bootstrap.rst identity-certificates-for-pki.rst identity-domain-specific-config.rst identity-external-authentication.rst diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index ba55ab7e7c..8186a060e5 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -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 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 ===================================