openstack
/
keystone
Code Issues Proposed changes
keystone/doc/source/configuration.rst

10 KiB
Raw Blame History

Configuring Keystone

Setting up other OpenStack Services

Creating Service Users

To configure the OpenStack services with service users, we need to create a project for all the services, and then users for each of the services. We then assign those service users an admin role on the service project. This allows them to validate tokens - and to authenticate and authorize other user requests.

Create a project for the services, typically named service (however, the name can be whatever you choose):

$ openstack project create service

Create service users for nova, glance, swift, and neutron (or whatever subset is relevant to your deployment):

$ openstack user create nova --password Sekr3tPass --project service

Repeat this for each service you want to enable.

Create an administrative role for the service accounts, typically named admin (however the name can be whatever you choose). For adding the administrative role to the service accounts, you'll need to know the name of the role you want to add. If you don't have it handy, you can look it up quickly with:

$ openstack role list

Once you have it, grant the administrative role to the service users.

$ openstack role add admin --project service --user nova

Defining Services

Keystone also acts as a service catalog to let other OpenStack systems know where relevant API endpoints exist for OpenStack Services. The OpenStack Dashboard, in particular, uses this heavily - and this must be configured for the OpenStack Dashboard to properly function.

The endpoints for these services are defined in a template, an example of which is in the project as the file etc/default_catalog.templates.

Keystone supports two means of defining the services, one is the catalog template, as described above - in which case everything is detailed in that template.

The other is a SQL backend for the catalog service, in which case after Keystone is online, you need to add the services to the catalog:

$ openstack service create compute --name nova \
                                --description "Nova Compute Service"
$ openstack service create ec2 --name ec2 \
                               --description "EC2 Compatibility Layer"
$ openstack service create image --name glance \
                                  --description "Glance Image Service"
$ openstack service create identity --name keystone \
                                    --description "Keystone Identity Service"
$ openstack service create object-store --name swift \
                                 --description "Swift Service"

Identity sources

One of the most impactful decisions you'll have to make when configuring keystone is deciding how you want keystone to source your identity data. Keystone supports several different choices that will substantially impact how you'll configure, deploy, and interact with keystone.

You can also mix-and-match various sources of identity (see Domain-specific Configuration for an example). For example, you can store OpenStack service users and their passwords in SQL, manage customers in LDAP, and authenticate employees via SAML federation.

Public ID Generators

Keystone supports a customizable public ID generator and it is specified in the [identity_mapping] section of the configuration file. Keystone provides a sha256 generator as default, which produces regenerable public IDs. The generator algorithm for public IDs is a balance between key size (i.e. the length of the public ID), the probability of collision and, in some circumstances, the security of the public ID. The maximum length of public ID supported by keystone is 64 characters, and the default generator (sha256) uses this full capability. Since the public ID is what is exposed externally by keystone and potentially stored in external systems, some installations may wish to make use of other generator algorithms that have a different trade-off of attributes. A different generator can be installed by configuring the following property:

  • generator - identity mapping generator. Defaults to sha256 (implemented by keystone.identity.id_generators.sha256.Generator)

Warning

Changing the generator may cause all existing public IDs to be become invalid, so typically the generator selection should be considered immutable for a given installation.

Service Catalog

Keystone provides two configuration options for managing a service catalog.

SQL-based Service Catalog (sql.Catalog)

A dynamic database-backed driver fully supporting persistent configuration.

keystone.conf example:

[catalog]
driver = sql

Note

A template_file does not need to be defined for the sql based catalog.

To build your service catalog using this driver, see the built-in help:

$ openstack --help
$ openstack service create --help
$ openstack endpoint create --help

File-based Service Catalog (templated.Catalog)

The templated catalog is an in-memory backend initialized from a read-only template_file. Choose this option only if you know that your service catalog will not change very much over time.

Note

Attempting to change your service catalog against this driver will result in HTTP 501 Not Implemented errors. This is the expected behavior. If you want to use these commands, you must instead use the SQL-based Service Catalog driver.

keystone.conf example:

[catalog]
driver = templated
template_file = /opt/stack/keystone/etc/default_catalog.templates

The value of template_file is expected to be an absolute path to your service catalog configuration. An example template_file is included in keystone, however you should create your own to reflect your deployment.

Endpoint Policy

The Endpoint Policy feature provides associations between service endpoints and policies that are already stored in the Identity server and referenced by a policy ID.

Configure the endpoint policy backend driver in the [endpoint_policy] section. For example:

[endpoint_policy]
driver = sql

See API Specification for Endpoint Policy <https://developer.openstack.org/ api-ref/identity/v3-ext/index.html#os-endpoint-policy-api> for the details of API definition.

SSL

A secure deployment should have keystone running in a web server (such as Apache httpd), or behind an SSL terminator.

Limiting list return size

Keystone provides a method of setting a limit to the number of entities returned in a collection, which is useful to prevent overly long response times for list queries that have not specified a sufficiently narrow filter. This limit can be set globally by setting list_limit in the default section of keystone.conf, with no limit set by default. Individual driver sections may override this global value with a specific limit, for example:

[resource]
list_limit = 100

If a response to list_{entity} call has been truncated, then the response status code will still be 200 (OK), but the truncated attribute in the collection will be set to true.

Supported clients

There are two supported clients, python-keystoneclient project provides python bindings and python-openstackclient provides a command line interface.

Authenticating with a Password via CLI

To authenticate with keystone using a password and python-openstackclient, set the following flags, note that the following user referenced below should be granted the admin role.

  • --os-username OS_USERNAME: Name of your user
  • --os-password OS_PASSWORD: Password for your user
  • --os-project-name OS_PROJECT_NAME: Name of your project
  • --os-auth-url OS_AUTH_URL: URL of the keystone authentication server

You can also set these variables in your environment so that they do not need to be passed as arguments each time:

$ export OS_USERNAME=my_username
$ export OS_PASSWORD=my_password
$ export OS_PROJECT_NAME=my_project
$ export OS_AUTH_URL=http://localhost:5000/v3

For example, the commands user list, token issue and project create can be invoked as follows:

# Using password authentication, with environment variables
$ export OS_USERNAME=admin
$ export OS_PASSWORD=secret
$ export OS_PROJECT_NAME=admin
$ export OS_AUTH_URL=http://localhost:5000/v3
$ openstack user list
$ openstack project create demo
$ openstack token issue

# Using password authentication, with flags
$ openstack --os-username=admin --os-password=secret --os-project-name=admin --os-auth-url=http://localhost:5000/v3 user list
$ openstack --os-username=admin --os-password=secret --os-project-name=admin --os-auth-url=http://localhost:5000/v3 project create demo