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-managebootstrap command. This is the preferred and
recommended way to bootstrap 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.

The process requires access to an environment with keystone binaries
installed, typically on the service host.

The keystone-managebootstrap 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.

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.

This command will also create member and reader roles. The admin
role implies the member role and member role implies the reader
role.

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.

We strongly recommended that you configure the identity service with the
keystone-managebootstrap 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. You shouldn’t have to use ADMIN_TOKEN at all, unless you have
some special case bootstrapping requirements.

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:

[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. After bootstrapping, failure to remove this functionality exposes an
additional attack vector and security risk.