2012-01-24 09:43:06 -08:00
|
|
|
..
|
2013-08-26 06:32:10 -07:00
|
|
|
Copyright 2011-2012 OpenStack Foundation
|
2012-01-24 09:43:06 -08:00
|
|
|
All Rights Reserved.
|
|
|
|
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
|
|
not use this file except in compliance with the License. You may obtain
|
|
|
|
a copy of the License at
|
|
|
|
|
2012-03-26 09:31:11 -07:00
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
2012-01-24 09:43:06 -08:00
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
|
|
License for the specific language governing permissions and limitations
|
|
|
|
under the License.
|
|
|
|
|
|
|
|
====================
|
|
|
|
Configuring Keystone
|
|
|
|
====================
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Config Files
|
|
|
|
============
|
2012-01-24 09:43:06 -08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Once keystone is installed, keystone is configured via a primary configuration
|
|
|
|
file (``etc/keystone.conf``), a PasteDeploy configuration file
|
2013-11-22 13:38:47 -06:00
|
|
|
(``etc/keystone-paste.ini``), possibly a separate logging configuration file,
|
2016-10-17 18:11:15 -07:00
|
|
|
and initializing data into keystone using the command line client.
|
2013-11-22 13:38:47 -06:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
The keystone configuration files are an ``ini`` file format based on Paste_, a
|
2015-01-09 23:51:12 -03:00
|
|
|
common system used to configure Python WSGI based applications. The PasteDeploy
|
|
|
|
configuration entries (WSGI pipeline definitions) can be provided in a separate
|
|
|
|
``keystone-paste.ini`` file, while general and driver-specific configuration
|
2014-11-13 23:20:23 +08:00
|
|
|
parameters are in the primary configuration file ``keystone.conf``.
|
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
|
|
|
Since keystone's PasteDeploy configuration file has been separated
|
|
|
|
from the main keystone configuration file, ``keystone.conf``, all
|
|
|
|
local configuration or driver-specific configuration parameters must
|
|
|
|
go in the main keystone configuration file instead of the PasteDeploy
|
|
|
|
configuration file, i.e. configuration in ``keystone-paste.ini``
|
|
|
|
is not supported.
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Sample Configuration Files
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
The ``etc/`` folder distributed with keystone contains example configuration
|
|
|
|
files for each Server application.
|
|
|
|
|
|
|
|
* ``etc/keystone.conf.sample``
|
|
|
|
* ``etc/keystone-paste.ini``
|
|
|
|
* ``etc/logging.conf.sample``
|
|
|
|
* ``etc/default_catalog.templates``
|
|
|
|
* ``etc/sso_callback_template.html``
|
|
|
|
|
|
|
|
``keystone.conf`` sections
|
|
|
|
--------------------------
|
|
|
|
|
2014-11-13 23:20:23 +08:00
|
|
|
The primary configuration file is organized into the following sections:
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[DEFAULT]`` - General configuration
|
|
|
|
* ``[assignment]`` - Assignment system driver configuration
|
|
|
|
* ``[auth]`` - Authentication plugin configuration
|
|
|
|
* ``[cache]`` - Caching layer configuration
|
|
|
|
* ``[catalog]`` - Service catalog driver configuration
|
|
|
|
* ``[credential]`` - Credential system driver configuration
|
2016-09-07 17:04:21 -07:00
|
|
|
* ``[domain_config]`` - Domain configuration
|
2015-11-20 11:22:59 +08:00
|
|
|
* ``[endpoint_filter]`` - Endpoint filtering configuration
|
|
|
|
* ``[endpoint_policy]`` - Endpoint policy configuration
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[federation]`` - Federation driver configuration
|
2016-09-07 17:04:21 -07:00
|
|
|
* ``[fernet_tokens]`` - Fernet token configuration
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[identity]`` - Identity system driver configuration
|
|
|
|
* ``[identity_mapping]`` - Identity mapping system driver configuration
|
|
|
|
* ``[ldap]`` - LDAP configuration options
|
|
|
|
* ``[memcache]`` - Memcache configuration options
|
2014-06-24 13:50:31 +00:00
|
|
|
* ``[oauth1]`` - OAuth 1.0a system driver configuration
|
2013-03-09 01:58:33 +01:00
|
|
|
* ``[paste_deploy]`` - Pointer to the PasteDeploy configuration file
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[policy]`` - Policy system driver configuration for RBAC
|
2015-01-02 00:22:04 +00:00
|
|
|
* ``[resource]`` - Resource system driver configuration
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[revoke]`` - Revocation system driver configuration
|
2014-12-28 17:12:59 +00:00
|
|
|
* ``[role]`` - Role system driver configuration
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[saml]`` - SAML configuration options
|
2016-09-07 17:04:21 -07:00
|
|
|
* ``[security_compliance]`` - Security compliance configuration
|
|
|
|
* ``[shadow_users]`` - Shadow user configuration
|
2014-09-03 02:08:29 -04:00
|
|
|
* ``[signing]`` - Cryptographic signatures for PKI based tokens
|
|
|
|
* ``[token]`` - Token driver & token provider configuration
|
2016-09-07 17:04:21 -07:00
|
|
|
* ``[tokenless_auth]`` - Tokenless authentication configuration
|
2016-02-16 15:14:53 +00:00
|
|
|
* ``[trust]`` - Trust configuration
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
The keystone primary configuration file is expected to be named
|
|
|
|
``keystone.conf``. When starting keystone, you can specify a different
|
2015-01-09 23:51:12 -03:00
|
|
|
configuration file to use with ``--config-file``. If you do **not** specify a
|
2016-10-17 18:11:15 -07:00
|
|
|
configuration file, keystone will look in the following directories for a
|
2015-01-09 23:51:12 -03:00
|
|
|
configuration file, in order:
|
2012-01-24 09:43:06 -08:00
|
|
|
|
2012-03-01 12:31:53 -06:00
|
|
|
* ``~/.keystone/``
|
2012-01-24 09:43:06 -08:00
|
|
|
* ``~/``
|
2012-03-01 12:31:53 -06:00
|
|
|
* ``/etc/keystone/``
|
|
|
|
* ``/etc/``
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
PasteDeploy configuration file is specified by the ``config_file`` parameter in
|
|
|
|
``[paste_deploy]`` section of the primary configuration file. If the parameter
|
2016-10-17 18:11:15 -07:00
|
|
|
is not an absolute path, then keystone looks for it in the same directories as
|
2014-09-25 03:51:08 -04:00
|
|
|
above. If not specified, WSGI pipeline definitions are loaded from the primary
|
|
|
|
configuration file.
|
2012-10-09 20:13:34 -04:00
|
|
|
|
2016-11-18 17:24:46 -05:00
|
|
|
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
|
|
|
|
===================================
|
|
|
|
|
|
|
|
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):
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ openstack project create service
|
|
|
|
|
|
|
|
Create service users for ``nova``, ``glance``, ``swift``, and ``neutron``
|
|
|
|
(or whatever subset is relevant to your deployment):
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ 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:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ openstack role list
|
|
|
|
|
|
|
|
Once you have it, grant the administrative role to the service users.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ 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:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ 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"
|
|
|
|
|
|
|
|
|
2016-08-29 08:27:24 -05:00
|
|
|
Identity sources
|
2016-11-18 13:46:23 -05:00
|
|
|
================
|
2016-08-29 08:27:24 -05:00
|
|
|
|
|
|
|
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
|
|
|
|
Drivers`_ below 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.
|
|
|
|
|
|
|
|
.. support_matrix:: identity-support-matrix.ini
|
|
|
|
|
|
|
|
.. Domain-specific Drivers:
|
|
|
|
|
2013-09-06 15:08:20 -05:00
|
|
|
Domain-specific Drivers
|
|
|
|
-----------------------
|
|
|
|
|
2013-07-25 20:09:45 +01:00
|
|
|
Keystone supports the option (disabled by default) to specify identity driver
|
|
|
|
configurations on a domain by domain basis, allowing, for example, a specific
|
|
|
|
domain to have its own LDAP or SQL server. This is configured by specifying the
|
2014-09-25 03:51:08 -04:00
|
|
|
following options:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-07-25 20:09:45 +01:00
|
|
|
|
|
|
|
[identity]
|
|
|
|
domain_specific_drivers_enabled = True
|
|
|
|
domain_config_dir = /etc/keystone/domains
|
|
|
|
|
2013-09-06 15:08:20 -05:00
|
|
|
Setting ``domain_specific_drivers_enabled`` to ``True`` will enable this
|
2016-10-17 18:11:15 -07:00
|
|
|
feature, causing keystone to look in the ``domain_config_dir`` for config files
|
2013-09-06 15:08:20 -05:00
|
|
|
of the form::
|
2013-07-25 20:09:45 +01:00
|
|
|
|
|
|
|
keystone.<domain_name>.conf
|
|
|
|
|
2013-09-06 15:08:20 -05:00
|
|
|
Options given in the domain specific configuration file will override those in
|
|
|
|
the primary configuration file for the specified domain only. Domains without a
|
|
|
|
specific configuration file will continue to use the options from the primary
|
|
|
|
configuration file.
|
2013-07-25 20:09:45 +01:00
|
|
|
|
2015-03-19 09:44:28 +00:00
|
|
|
Keystone also supports the ability to store the domain-specific configuration
|
|
|
|
options in the keystone SQL database, managed via the Identity API, as opposed
|
|
|
|
to using domain-specific configuration files.
|
|
|
|
|
|
|
|
This capability (which is disabled by default) is enabled by specifying the
|
|
|
|
following options in the main keystone configuration file:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
[identity]
|
|
|
|
domain_specific_drivers_enabled = true
|
|
|
|
domain_configurations_from_database = true
|
2015-03-19 09:44:28 +00:00
|
|
|
|
|
|
|
Once enabled, any existing domain-specific configuration files in the
|
|
|
|
configuration directory will be ignored and only those domain-specific
|
|
|
|
configuration options specified via the Identity API will be used.
|
|
|
|
|
2015-03-09 09:13:04 +00:00
|
|
|
Unlike the file-based method of specifying domain-specific configurations,
|
|
|
|
options specified via the Identity API will become active without needing to
|
|
|
|
restart the keystone server. For performance reasons, the current state of
|
|
|
|
configuration options for a domain are cached in the keystone server, and in
|
|
|
|
multi-process and multi-threaded keystone configurations, the new
|
|
|
|
configuration options may not become active until the cache has timed out. The
|
|
|
|
cache settings for domain config options can be adjusted in the general
|
2015-07-22 17:48:19 +08:00
|
|
|
keystone configuration file (option ``cache_time`` in the ``domain_config``
|
2015-03-09 09:13:04 +00:00
|
|
|
group).
|
|
|
|
|
2015-03-19 09:44:28 +00:00
|
|
|
.. NOTE::
|
|
|
|
|
|
|
|
It is important to notice that when using either of these methods of
|
|
|
|
specifying domain-specific configuration options, the main keystone
|
|
|
|
configuration file is still maintained. Only those options that relate
|
|
|
|
to the Identity driver for users and groups (i.e. specifying whether the
|
|
|
|
driver for this domain is SQL or LDAP, and, if LDAP, the options that
|
2015-03-09 09:13:04 +00:00
|
|
|
define that connection) are supported in a domain-specific manner. Further,
|
|
|
|
when using the configuration options via the Identity API, the driver
|
|
|
|
option must be set to an LDAP driver (attempting to set it to an SQL driver
|
|
|
|
will generate an error when it is subsequently used).
|
2015-03-19 09:44:28 +00:00
|
|
|
|
|
|
|
For existing installations that already use file-based domain-specific
|
|
|
|
configurations who wish to migrate to the SQL-based approach, the
|
|
|
|
``keystone-manage`` command can be used to upload all configuration files to
|
|
|
|
the SQL database:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ keystone-manage domain_config_upload --all
|
|
|
|
|
|
|
|
Once uploaded, these domain-configuration options will be visible via the
|
|
|
|
Identity API as well as applied to the domain-specific drivers. It is also
|
|
|
|
possible to upload individual domain-specific configuration files by
|
|
|
|
specifying the domain name:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ keystone-manage domain_config_upload --domain-name DOMAINA
|
|
|
|
|
2014-10-30 21:48:42 -03:00
|
|
|
.. NOTE::
|
|
|
|
|
2015-03-19 09:44:28 +00:00
|
|
|
It is important to notice that by enabling either of the domain-specific
|
|
|
|
configuration methods, the operations of listing all users and listing all
|
|
|
|
groups are not supported, those calls will need either a domain filter to
|
|
|
|
be specified or usage of a domain scoped token.
|
2014-10-30 21:48:42 -03:00
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
.. NOTE::
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Keystone does not support moving the contents of a domain (i.e. "its" users
|
|
|
|
and groups) from one backend to another, nor group membership across
|
2014-06-25 06:26:38 +01:00
|
|
|
backend boundaries.
|
|
|
|
|
2014-10-27 22:24:52 -03:00
|
|
|
.. NOTE::
|
|
|
|
|
2015-03-19 09:44:28 +00:00
|
|
|
When using the file-based domain-specific configuration method, to delete a
|
|
|
|
domain that uses a domain specific backend, it's necessary to first disable
|
|
|
|
it, remove its specific configuration file (i.e. its corresponding
|
|
|
|
keystone.<domain_name>.conf) and then restart the Identity server. When
|
|
|
|
managing configuration options via the Identity API, the domain can simply
|
|
|
|
be disabled and deleted via the Identity API; since any domain-specific
|
|
|
|
configuration options will automatically be removed.
|
2014-10-27 22:24:52 -03:00
|
|
|
|
2014-09-10 12:18:27 +01:00
|
|
|
.. NOTE::
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Although keystone supports multiple LDAP backends via the above
|
2015-03-19 09:44:28 +00:00
|
|
|
domain-specific configuration methods, it currently only supports one SQL
|
|
|
|
backend. This could be either the default driver or a single
|
|
|
|
domain-specific backend, perhaps for storing service users in a
|
|
|
|
predominantly LDAP installation.
|
2014-09-10 12:18:27 +01:00
|
|
|
|
2016-07-07 14:49:30 -07:00
|
|
|
.. NOTE::
|
|
|
|
|
|
|
|
Keystone has deprecated the ``keystone-manage domain_config_upload``
|
|
|
|
option. The keystone team recommends setting domain config options via the
|
|
|
|
API instead.
|
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
Due to the need for user and group IDs to be unique across an OpenStack
|
2016-10-17 18:11:15 -07:00
|
|
|
installation and for keystone to be able to deduce which domain and backend to
|
2014-06-25 06:26:38 +01:00
|
|
|
use from just a user or group ID, it dynamically builds a persistent identity
|
|
|
|
mapping table from a public ID to the actual domain, local ID (within that
|
2016-10-17 18:11:15 -07:00
|
|
|
backend) and entity type. The public ID is automatically generated by keystone
|
2015-01-09 23:51:12 -03:00
|
|
|
when it first encounters the entity. If the local ID of the entity is from a
|
|
|
|
backend that does not guarantee to generate UUIDs, a hash algorithm will
|
2014-06-25 06:26:38 +01:00
|
|
|
generate a public ID for that entity, which is what will be exposed by
|
2016-10-17 18:11:15 -07:00
|
|
|
keystone.
|
2014-06-25 06:26:38 +01:00
|
|
|
|
|
|
|
The use of a hash will ensure that if the public ID needs to be regenerated
|
2015-01-09 23:11:15 -03:00
|
|
|
then the same public ID will be created. This is useful if you are running
|
2014-06-25 06:26:38 +01:00
|
|
|
multiple keystones and want to ensure the same ID would be generated whichever
|
|
|
|
server you hit.
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
While keystone will dynamically maintain the identity mapping, including
|
|
|
|
removing entries when entities are deleted via the keystone, for those entities
|
|
|
|
in backends that are managed outside of keystone (e.g. a read-only LDAP),
|
|
|
|
keystone will not know if entities have been deleted and hence will continue to
|
2015-01-09 23:51:12 -03:00
|
|
|
carry stale identity mappings in its table. While benign, keystone provides an
|
|
|
|
ability for operators to purge the mapping table of such stale entries using
|
|
|
|
the keystone-manage command, for example:
|
2014-06-25 06:26:38 +01:00
|
|
|
|
2014-08-27 13:17:03 -04:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
$ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
A typical usage would be for an operator to obtain a list of those entries in
|
2016-10-17 18:11:15 -07:00
|
|
|
an external backend that had been deleted out-of-band to keystone, and then
|
2014-06-25 06:26:38 +01:00
|
|
|
call keystone-manage to purge those entries by specifying the domain and
|
2015-01-09 23:51:12 -03:00
|
|
|
local-id. The type of the entity (i.e. user or group) may also be specified if
|
|
|
|
this is needed to uniquely identify the mapping.
|
2014-06-25 06:26:38 +01:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Since public IDs can be regenerated **with the correct generator
|
|
|
|
implementation**, if the details of those entries that have been deleted are
|
|
|
|
not available, then it is safe to simply bulk purge identity mappings
|
|
|
|
periodically, for example:
|
2014-06-25 06:26:38 +01:00
|
|
|
|
2014-08-27 13:17:03 -04:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
$ keystone-manage mapping_purge --domain-name DOMAINA
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
will purge all the mappings for DOMAINA. The entire mapping table can be purged
|
|
|
|
with the following command:
|
2014-06-25 06:26:38 +01:00
|
|
|
|
2014-08-27 13:17:03 -04:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
$ keystone-manage mapping_purge --all
|
|
|
|
|
2016-07-15 20:57:45 +03:00
|
|
|
Generating public IDs in the first run may take a while, and most probably
|
|
|
|
first API requests to fetch user list will fail by timeout. To prevent this,
|
|
|
|
``mapping_populate`` command should be executed. It should be executed right after
|
|
|
|
LDAP has been configured or after ``mapping_purge``.
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ keystone-manage mapping_populate --domain DOMAINA
|
|
|
|
|
2014-06-25 06:26:38 +01:00
|
|
|
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
|
2017-02-20 10:32:30 +08:00
|
|
|
sha256 generator as default, which produces regenerable public IDs. The
|
2014-06-25 06:26:38 +01:00
|
|
|
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
|
2015-01-09 23:11:15 -03:00
|
|
|
circumstances, the security of the public ID. The maximum length of public ID
|
2016-10-17 18:11:15 -07:00
|
|
|
supported by keystone is 64 characters, and the default generator (sha256) uses
|
2015-01-09 23:11:15 -03:00
|
|
|
this full capability. Since the public ID is what is exposed externally by
|
2016-10-17 18:11:15 -07:00
|
|
|
keystone and potentially stored in external systems, some installations may
|
2014-06-25 06:26:38 +01:00
|
|
|
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:
|
|
|
|
|
2015-08-07 14:24:41 -05:00
|
|
|
* ``generator`` - identity mapping generator. Defaults to ``sha256``
|
|
|
|
(implemented by :class:`keystone.identity.id_generators.sha256.Generator`)
|
2014-06-25 06:26:38 +01:00
|
|
|
|
|
|
|
.. 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.
|
|
|
|
|
2013-01-08 08:46:20 -08:00
|
|
|
Authentication Plugins
|
2016-11-18 13:46:23 -05:00
|
|
|
======================
|
2013-01-08 08:46:20 -08:00
|
|
|
|
2014-05-01 10:56:18 -07:00
|
|
|
.. NOTE::
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
This feature is only supported by keystone for the Identity API v3 clients.
|
2014-05-01 10:56:18 -07:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Keystone supports authentication plugins and they are specified in the
|
|
|
|
``[auth]`` section of the configuration file. However, an authentication plugin
|
|
|
|
may also have its own section in the configuration file. It is up to the plugin
|
|
|
|
to register its own configuration options.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
* ``methods`` - comma-delimited list of authentication plugin names
|
2014-09-25 03:51:08 -04:00
|
|
|
* ``<plugin name>`` - specify the class which handles to authentication method,
|
|
|
|
in the same manner as one would specify a backend driver.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Keystone provides three authentication methods by default. ``password`` handles
|
|
|
|
password authentication and ``token`` handles token authentication.
|
|
|
|
``external`` is used in conjunction with authentication performed by a
|
|
|
|
container web server that sets the ``REMOTE_USER`` environment variable. For
|
2017-06-17 14:12:37 +05:30
|
|
|
more details, refer to :doc:`External Authentication
|
|
|
|
<advanced-topics/external-auth>`.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
How to Implement an Authentication Plugin
|
2016-11-18 13:46:23 -05:00
|
|
|
-----------------------------------------
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
All authentication plugins must extend the
|
2016-07-07 16:19:28 +00:00
|
|
|
:class:`keystone.auth.plugins.base.AuthMethodHandler` class and implement the
|
2015-01-09 23:51:12 -03:00
|
|
|
``authenticate()`` method. The ``authenticate()`` method expects the following
|
|
|
|
parameters.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
* ``context`` - keystone's request context
|
2013-01-08 08:46:20 -08:00
|
|
|
* ``auth_payload`` - the content of the authentication for a given method
|
2014-09-25 03:51:08 -04:00
|
|
|
* ``auth_context`` - user authentication context, a dictionary shared by all
|
|
|
|
plugins. It contains ``method_names`` and ``extras`` by default.
|
|
|
|
``method_names`` is a list and ``extras`` is a dictionary.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
If successful, the ``authenticate()`` method must provide a valid ``user_id``
|
2015-01-09 23:51:12 -03:00
|
|
|
in ``auth_context`` and return ``None``. ``method_name`` is used to convey any
|
|
|
|
additional authentication methods in case authentication is for re-scoping. For
|
|
|
|
example, if the authentication is for re-scoping, a plugin must append the
|
|
|
|
previous method names into ``method_names``. Also, a plugin may add any
|
|
|
|
additional information into ``extras``. Anything in ``extras`` will be conveyed
|
|
|
|
in the token's ``extras`` field.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
If authentication requires multiple steps, the ``authenticate()`` method must
|
|
|
|
return the payload in the form of a dictionary for the next authentication
|
|
|
|
step.
|
|
|
|
|
|
|
|
If authentication is unsuccessful, the ``authenticate()`` method must raise a
|
2015-08-07 14:24:41 -05:00
|
|
|
:class:`keystone.exception.Unauthorized` exception.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
Simply add the new plugin name to the ``methods`` list along with your plugin
|
2015-01-09 23:51:12 -03:00
|
|
|
class configuration in the ``[auth]`` sections of the configuration file to
|
|
|
|
deploy it.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
2015-01-09 22:48:38 -03:00
|
|
|
If the plugin requires additional configurations, it may register its own
|
|
|
|
section in the configuration file.
|
2013-01-08 08:46:20 -08:00
|
|
|
|
|
|
|
Plugins are invoked in the order in which they are specified in the ``methods``
|
|
|
|
attribute of the ``authentication`` request body. If multiple plugins are
|
2015-01-09 23:51:12 -03:00
|
|
|
invoked, all plugins must succeed in order to for the entire authentication to
|
|
|
|
be successful. Furthermore, all the plugins invoked must agree on the
|
|
|
|
``user_id`` in the ``auth_context``.
|
|
|
|
|
|
|
|
The ``REMOTE_USER`` environment variable is only set from a containing
|
|
|
|
webserver. However, to ensure that a user must go through other authentication
|
|
|
|
mechanisms, even if this variable is set, remove ``external`` from the list of
|
|
|
|
plugins specified in ``methods``. This effectively disables external
|
2017-06-17 14:12:37 +05:30
|
|
|
authentication. For more details, refer to :doc:`External Authentication
|
|
|
|
<advanced-topics/external-auth>`.
|
2013-07-12 10:23:38 -04:00
|
|
|
|
2013-08-17 03:53:50 -07:00
|
|
|
Caching Layer
|
2016-11-18 13:46:23 -05:00
|
|
|
=============
|
2013-08-17 03:53:50 -07:00
|
|
|
|
2016-11-01 17:08:59 +00:00
|
|
|
Keystone's configuration file offers two separate sections related to caching,
|
|
|
|
``[memcache]`` and ``[cache]``. The ``[memcache]`` section provides caching
|
|
|
|
options to configure memcache backends. For example, if your deployment issues
|
|
|
|
UUID tokens (``[token] provider = uuid``) and your token storage driver is
|
|
|
|
memcache (``[token] driver = kvs``), the configuration options in the
|
|
|
|
``[memcache]`` section will effect token storage behavior. The ``[cache]``
|
|
|
|
section is provided through the ``oslo.cache`` library and consists of options
|
|
|
|
to configure the caching of data between a particular keystone subsystem (e.g.
|
|
|
|
``token``, ``identity``, etc) and its configured storage backend. For example,
|
|
|
|
if your deployment's identity backend is using SQL (``[identity] driver =
|
|
|
|
sql``) and you have caching enabled (``[cache] enabled = true``),
|
|
|
|
``oslo.cache`` will cache responses from SQL improving the overall performance
|
|
|
|
of the identity subsystem. The options in the ``[cache]`` section will effect
|
|
|
|
the caching layer in-between a keystone subsystem and its storage backend.
|
|
|
|
|
|
|
|
Keystone uses the `dogpile.cache`_ library which allows for flexible cache
|
|
|
|
backends. The majority of the caching configuration options are set in the
|
|
|
|
``[cache]`` section. However, each section that has the capability to be
|
|
|
|
cached usually has a ``caching`` boolean value that will toggle caching for
|
|
|
|
that specific section. The current default behavior is that global and
|
|
|
|
subsystem caching is enabled.
|
2013-08-17 03:53:50 -07:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
``[cache]`` configuration section
|
|
|
|
---------------------------------
|
2013-08-17 03:53:50 -07:00
|
|
|
|
|
|
|
* ``enabled`` - enables/disables caching across all of keystone
|
2015-01-09 23:51:12 -03:00
|
|
|
* ``debug_cache_backend`` - enables more in-depth logging from the cache
|
|
|
|
backend (get, set, delete, etc)
|
|
|
|
* ``backend`` - the caching backend module to use e.g.
|
|
|
|
``dogpile.cache.memcached``
|
2013-08-17 03:53:50 -07:00
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
A given ``backend`` must be registered with ``dogpile.cache`` before it
|
2016-10-17 18:11:15 -07:00
|
|
|
can be used. The default backend is the keystone no-op backend
|
2015-01-09 23:51:12 -03:00
|
|
|
(``keystone.common.cache.noop``). If caching is desired a different
|
|
|
|
backend will need to be specified. Current functional backends are:
|
|
|
|
|
|
|
|
* ``dogpile.cache.memcached`` - Memcached backend using the standard
|
2016-01-22 14:06:03 +00:00
|
|
|
`python-memcached`_ library (recommended for use with Apache httpd with
|
|
|
|
``mod_wsgi``)
|
2015-01-09 23:51:12 -03:00
|
|
|
* ``dogpile.cache.pylibmc`` - Memcached backend using the `pylibmc`_
|
|
|
|
library
|
|
|
|
* ``dogpile.cache.bmemcached`` - Memcached using `python-binary-memcached`_
|
|
|
|
library.
|
2013-08-17 03:53:50 -07:00
|
|
|
* ``dogpile.cache.redis`` - `Redis`_ backend
|
|
|
|
* ``dogpile.cache.dbm`` - local DBM file backend
|
|
|
|
* ``dogpile.cache.memory`` - in-memory cache
|
2016-07-08 10:01:13 +08:00
|
|
|
* ``oslo_cache.mongo`` - MongoDB as caching backend
|
|
|
|
* ``oslo_cache.memcache_pool`` - Memcache with pooling.
|
|
|
|
This implementation also provides client connection re-use.
|
2013-08-17 03:53:50 -07:00
|
|
|
|
|
|
|
.. WARNING::
|
2015-01-09 23:51:12 -03:00
|
|
|
``dogpile.cache.memory`` is not suitable for use outside of unit
|
|
|
|
testing as it does not cleanup its internal cache on cache
|
|
|
|
expiration, does not provide isolation to the cached data (values
|
|
|
|
in the store can be inadvertently changed without extra layers of
|
|
|
|
data protection added), and does not share cache between processes.
|
|
|
|
This means that caching and cache invalidation will not be
|
2016-10-17 18:11:15 -07:00
|
|
|
consistent or reliable when using ``keystone`` and the
|
2015-01-09 23:51:12 -03:00
|
|
|
``dogpile.cache.memory`` backend under any real workload.
|
2013-08-17 03:53:50 -07:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
* ``expiration_time`` - int, the default length of time to cache a specific
|
|
|
|
value. A value of ``0`` indicates to not cache anything. It is recommended
|
|
|
|
that the ``enabled`` option be used to disable cache instead of setting this
|
|
|
|
to ``0``.
|
2013-08-17 03:53:50 -07:00
|
|
|
* ``backend_argument`` - an argument passed to the backend when instantiated
|
2015-01-09 23:51:12 -03:00
|
|
|
``backend_argument`` should be specified once per argument to be passed to
|
|
|
|
the backend and in the format of ``<argument name>:<argument value>``. e.g.:
|
|
|
|
``backend_argument = host:localhost``
|
|
|
|
* ``proxies`` - comma delimited list of `ProxyBackends`_ e.g.
|
|
|
|
``my.example.Proxy, my.example.Proxy2``
|
2013-08-17 03:53:50 -07:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Current keystone systems that have caching capabilities:
|
2013-08-23 19:06:42 -07:00
|
|
|
* ``token``
|
2015-01-09 23:51:12 -03:00
|
|
|
The token system has a separate ``cache_time`` configuration option,
|
|
|
|
that can be set to a value above or below the global
|
|
|
|
``expiration_time`` default, allowing for different caching behavior
|
2016-10-17 18:11:15 -07:00
|
|
|
from the other systems in keystone. This option is set in the
|
2015-01-09 23:51:12 -03:00
|
|
|
``[token]`` section of the configuration file.
|
|
|
|
|
|
|
|
The Token Revocation List cache time is handled by the configuration
|
|
|
|
option ``revocation_cache_time`` in the ``[token]`` section. The
|
|
|
|
revocation list is refreshed whenever a token is revoked. It typically
|
|
|
|
sees significantly more requests than specific token retrievals or
|
|
|
|
token validation calls.
|
2015-01-02 00:22:04 +00:00
|
|
|
* ``resource``
|
|
|
|
The resource system has a separate ``cache_time`` configuration option,
|
|
|
|
that can be set to a value above or below the global
|
2015-01-09 23:51:12 -03:00
|
|
|
``expiration_time`` default, allowing for different caching behavior
|
2016-10-17 18:11:15 -07:00
|
|
|
from the other systems in keystone. This option is set in the
|
2015-01-02 00:22:04 +00:00
|
|
|
``[resource]`` section of the configuration file.
|
2013-08-24 21:07:32 -07:00
|
|
|
|
2015-01-02 00:22:04 +00:00
|
|
|
Currently ``resource`` has caching for ``project`` and ``domain``
|
|
|
|
specific requests (primarily around the CRUD actions). The
|
|
|
|
``list_projects`` and ``list_domains`` methods are not subject to
|
|
|
|
caching.
|
2013-08-24 21:07:32 -07:00
|
|
|
|
|
|
|
.. WARNING::
|
2015-01-02 00:22:04 +00:00
|
|
|
Be aware that if a read-only ``resource`` backend is in use, the
|
|
|
|
cache will not immediately reflect changes on the back end. Any
|
2015-01-09 23:51:12 -03:00
|
|
|
given change may take up to the ``cache_time`` (if set in the
|
2015-01-02 00:22:04 +00:00
|
|
|
``[resource]`` section of the configuration) or the global
|
2015-01-09 23:51:12 -03:00
|
|
|
``expiration_time`` (set in the ``[cache]`` section of the
|
|
|
|
configuration) before it is reflected. If this type of delay (when
|
2015-01-02 00:22:04 +00:00
|
|
|
using a read-only ``resource`` backend) is an issue, it is
|
|
|
|
recommended that caching be disabled on ``resource``. To disable
|
|
|
|
caching specifically on ``resource``, in the ``[resource]`` section
|
|
|
|
of the configuration set ``caching`` to ``False``.
|
2014-12-28 17:12:59 +00:00
|
|
|
* ``role``
|
|
|
|
Currently ``role`` has caching for ``get_role``, but not for ``list_roles``.
|
|
|
|
The role system has a separate ``cache_time`` configuration option,
|
|
|
|
that can be set to a value above or below the global ``expiration_time``
|
|
|
|
default, allowing for different caching behavior from the other systems in
|
2016-10-17 18:11:15 -07:00
|
|
|
keystone. This option is set in the ``[role]`` section of the
|
2014-12-28 17:12:59 +00:00
|
|
|
configuration file.
|
|
|
|
|
|
|
|
.. WARNING::
|
|
|
|
Be aware that if a read-only ``role`` backend is in use, the cache
|
|
|
|
will not immediately reflect changes on the back end. Any given change
|
|
|
|
may take up to the ``cache_time`` (if set in the ``[role]``
|
|
|
|
section of the configuration) or the global ``expiration_time`` (set in
|
|
|
|
the ``[cache]`` section of the configuration) before it is reflected.
|
|
|
|
If this type of delay (when using a read-only ``role`` backend) is
|
|
|
|
an issue, it is recommended that caching be disabled on ``role``.
|
|
|
|
To disable caching specifically on ``role``, in the ``[role]``
|
|
|
|
section of the configuration set ``caching`` to ``False``.
|
2013-08-23 19:06:42 -07:00
|
|
|
|
2013-08-17 03:53:50 -07:00
|
|
|
For more information about the different backends (and configuration options):
|
|
|
|
* `dogpile.cache.backends.memory`_
|
|
|
|
* `dogpile.cache.backends.memcached`_
|
|
|
|
* `dogpile.cache.backends.redis`_
|
|
|
|
* `dogpile.cache.backends.file`_
|
|
|
|
|
|
|
|
.. _`dogpile.cache`: http://dogpilecache.readthedocs.org/en/latest/
|
|
|
|
.. _`python-memcached`: http://www.tummy.com/software/python-memcached/
|
|
|
|
.. _`pylibmc`: http://sendapatch.se/projects/pylibmc/index.html
|
|
|
|
.. _`python-binary-memcached`: https://github.com/jaysonsantos/python-binary-memcached
|
|
|
|
.. _`Redis`: http://redis.io/
|
|
|
|
.. _`dogpile.cache.backends.memory`: http://dogpilecache.readthedocs.org/en/latest/api.html#memory-backend
|
|
|
|
.. _`dogpile.cache.backends.memcached`: http://dogpilecache.readthedocs.org/en/latest/api.html#memcached-backends
|
|
|
|
.. _`dogpile.cache.backends.redis`: http://dogpilecache.readthedocs.org/en/latest/api.html#redis-backends
|
|
|
|
.. _`dogpile.cache.backends.file`: http://dogpilecache.readthedocs.org/en/latest/api.html#file-backends
|
|
|
|
.. _`ProxyBackends`: http://dogpilecache.readthedocs.org/en/latest/api.html#proxy-backends
|
|
|
|
|
|
|
|
|
2012-10-09 20:13:34 -04:00
|
|
|
Certificates for PKI
|
2016-11-18 13:46:23 -05:00
|
|
|
====================
|
2012-10-09 20:13:34 -04:00
|
|
|
|
2015-01-09 23:11:15 -03:00
|
|
|
PKI stands for Public Key Infrastructure. Tokens are documents,
|
|
|
|
cryptographically signed using the X509 standard. In order to work correctly
|
|
|
|
token generation requires a public/private key pair. The public key must be
|
2012-10-09 20:13:34 -04:00
|
|
|
signed in an X509 certificate, and the certificate used to sign it must be
|
2015-01-09 23:11:15 -03:00
|
|
|
available as Certificate Authority (CA) certificate. These files can be either
|
2014-10-27 20:20:28 -05:00
|
|
|
externally generated or generated using the ``keystone-manage`` utility.
|
2014-03-16 00:03:43 -07:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
The files used for signing and verifying certificates are set in the keystone
|
2014-10-27 20:20:28 -05:00
|
|
|
configuration file. The private key should only be readable by the system user
|
2016-10-17 18:11:15 -07:00
|
|
|
that will run keystone. The values that specify the certificates are under the
|
2015-01-09 23:11:15 -03:00
|
|
|
``[signing]`` section of the configuration file. The configuration values are:
|
2012-10-09 20:13:34 -04:00
|
|
|
|
2015-01-09 23:11:15 -03:00
|
|
|
* ``certfile`` - Location of certificate used to verify tokens. Default is
|
2014-09-25 03:51:08 -04:00
|
|
|
``/etc/keystone/ssl/certs/signing_cert.pem``
|
2015-01-09 23:11:15 -03:00
|
|
|
* ``keyfile`` - Location of private key used to sign tokens. Default is
|
2014-09-25 03:51:08 -04:00
|
|
|
``/etc/keystone/ssl/private/signing_key.pem``
|
|
|
|
* ``ca_certs`` - Location of certificate for the authority that issued the
|
|
|
|
above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem``
|
2012-10-09 20:13:34 -04:00
|
|
|
|
2012-11-05 12:22:29 -08:00
|
|
|
Signing Certificate Issued by External CA
|
2016-11-18 13:46:23 -05:00
|
|
|
-----------------------------------------
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
You may use a signing certificate issued by an external CA instead of generated
|
2014-10-27 20:20:28 -05:00
|
|
|
by ``keystone-manage``. However, certificate issued by external CA must satisfy
|
2012-11-05 12:22:29 -08:00
|
|
|
the following conditions:
|
|
|
|
|
|
|
|
* all certificate and key files must be in Privacy Enhanced Mail (PEM) format
|
|
|
|
* private key files must not be protected by a password
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
The basic workflow for using a signing certificate issued by an external CA
|
|
|
|
involves:
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
1. `Request Signing Certificate from External CA`_
|
2014-06-24 13:50:31 +00:00
|
|
|
2. Convert certificate and private key to PEM if needed
|
2012-11-05 12:22:29 -08:00
|
|
|
3. `Install External Signing Certificate`_
|
|
|
|
|
|
|
|
|
|
|
|
Request Signing Certificate from External CA
|
2016-11-18 13:46:23 -05:00
|
|
|
--------------------------------------------
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
One way to request a signing certificate from an external CA is to first
|
|
|
|
generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI.
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
First create a certificate request configuration file (e.g. ``cert_req.conf``):
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
[ req ]
|
2013-01-22 15:05:45 +01:00
|
|
|
default_bits = 2048
|
2012-11-05 12:22:29 -08:00
|
|
|
default_keyfile = keystonekey.pem
|
2013-01-22 15:05:45 +01:00
|
|
|
default_md = default
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
prompt = no
|
|
|
|
distinguished_name = distinguished_name
|
|
|
|
|
|
|
|
[ distinguished_name ]
|
|
|
|
countryName = US
|
|
|
|
stateOrProvinceName = CA
|
|
|
|
localityName = Sunnyvale
|
|
|
|
organizationName = OpenStack
|
|
|
|
organizationalUnitName = Keystone
|
|
|
|
commonName = Keystone Signing
|
|
|
|
emailAddress = keystone@openstack.org
|
|
|
|
|
|
|
|
Then generate a CRS with OpenSSL CLI. **Do not encrypt the generated private
|
2014-10-27 20:20:28 -05:00
|
|
|
key. The -nodes option must be used.**
|
2012-11-05 12:22:29 -08:00
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-11-05 12:22:29 -08:00
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
$ openssl req -newkey rsa:2048 -keyout signing_key.pem -keyform PEM -out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
|
|
|
|
If everything is successfully, you should end up with ``signing_cert_req.pem``
|
2014-09-25 03:51:08 -04:00
|
|
|
and ``signing_key.pem``. Send ``signing_cert_req.pem`` to your CA to request a
|
|
|
|
token signing certificate and make sure to ask the certificate to be in PEM
|
2015-01-09 23:51:12 -03:00
|
|
|
format. Also, make sure your trusted CA certificate chain is also in PEM
|
|
|
|
format.
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
|
|
|
|
Install External Signing Certificate
|
2016-11-18 13:46:23 -05:00
|
|
|
------------------------------------
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
Assuming you have the following already:
|
|
|
|
|
|
|
|
* ``signing_cert.pem`` - (Keystone token) signing certificate in PEM format
|
|
|
|
* ``signing_key.pem`` - corresponding (non-encrypted) private key in PEM format
|
|
|
|
* ``cacert.pem`` - trust CA certificate chain in PEM format
|
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
Copy the above to your certificate directory. For example:
|
2012-11-05 12:22:29 -08:00
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ mkdir -p /etc/keystone/ssl/certs
|
|
|
|
$ cp signing_cert.pem /etc/keystone/ssl/certs/
|
|
|
|
$ cp signing_key.pem /etc/keystone/ssl/certs/
|
|
|
|
$ cp cacert.pem /etc/keystone/ssl/certs/
|
|
|
|
$ chmod -R 700 /etc/keystone/ssl/certs
|
2012-11-05 12:22:29 -08:00
|
|
|
|
|
|
|
**Make sure the certificate directory is root-protected.**
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
If your certificate directory path is different from the default
|
2015-01-09 23:51:12 -03:00
|
|
|
``/etc/keystone/ssl/certs``, make sure it is reflected in the ``[signing]``
|
|
|
|
section of the configuration file.
|
2012-10-09 20:13:34 -04:00
|
|
|
|
|
|
|
|
2012-03-26 10:27:15 -07:00
|
|
|
Service Catalog
|
2016-11-18 13:46:23 -05:00
|
|
|
===============
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Keystone provides two configuration options for managing a service catalog.
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
SQL-based Service Catalog (``sql.Catalog``)
|
2016-11-18 13:46:23 -05:00
|
|
|
-------------------------------------------
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
A dynamic database-backed driver fully supporting persistent configuration.
|
|
|
|
|
|
|
|
``keystone.conf`` example:
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
.. code-block:: ini
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
[catalog]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = sql
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
A `template_file` does not need to be defined for the sql based catalog.
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
To build your service catalog using this driver, see the built-in help:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2014-09-26 00:58:00 -04:00
|
|
|
$ openstack --help
|
2016-11-18 13:46:23 -05:00
|
|
|
$ openstack service create --help
|
|
|
|
$ openstack endpoint create --help
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2014-01-16 08:18:13 -06:00
|
|
|
File-based Service Catalog (``templated.Catalog``)
|
2016-11-18 13:46:23 -05:00
|
|
|
--------------------------------------------------
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
The templated catalog is an in-memory backend initialized from a read-only
|
2015-01-09 23:51:12 -03:00
|
|
|
``template_file``. Choose this option only if you know that your service
|
|
|
|
catalog will not change very much over time.
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
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
|
2012-03-26 10:27:15 -07:00
|
|
|
Catalog driver.
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
``keystone.conf`` example:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-03-26 10:27:15 -07:00
|
|
|
|
|
|
|
[catalog]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = templated
|
2012-03-26 10:27:15 -07:00
|
|
|
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
|
2016-10-17 18:11:15 -07:00
|
|
|
keystone, however you should create your own to reflect your deployment.
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Endpoint Filtering
|
|
|
|
==================
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2015-11-20 11:22:59 +08:00
|
|
|
Endpoint Filtering enables creation of ad-hoc catalogs for each project-scoped
|
|
|
|
token request.
|
|
|
|
|
|
|
|
Configure the endpoint filter catalog driver in the ``[catalog]`` section.
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[catalog]
|
|
|
|
driver = catalog_sql
|
|
|
|
|
|
|
|
In the ``[endpoint_filter]`` section, set ``return_all_endpoints_if_no_filter``
|
|
|
|
to ``False`` to return an empty catalog if no associations are made.
|
|
|
|
For example:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[endpoint_filter]
|
|
|
|
return_all_endpoints_if_no_filter = False
|
|
|
|
|
2017-01-30 13:53:09 -08:00
|
|
|
See `API Specification for Endpoint Filtering <https://developer.openstack.org/
|
2016-09-23 18:05:10 +00:00
|
|
|
api-ref/identity/v3-ext/#os-ep-filter-api>`_ for the details of API definition.
|
2015-11-20 11:22:59 +08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Endpoint Policy
|
|
|
|
===============
|
2015-11-20 11:22:59 +08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
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:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[endpoint_policy]
|
|
|
|
driver = sql
|
|
|
|
|
2017-05-01 21:15:02 +02:00
|
|
|
See `API Specification for Endpoint Policy <https://developer.openstack.org/
|
|
|
|
api-ref/identity/v3-ext/index.html#os-endpoint-policy-api>`_
|
2016-11-18 13:46:23 -05:00
|
|
|
for the details of API definition.
|
2015-11-20 11:22:59 +08:00
|
|
|
|
2012-03-26 10:27:15 -07:00
|
|
|
Logging
|
2016-11-18 13:46:23 -05:00
|
|
|
=======
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Logging is configured externally to the rest of keystone. Configure the path to
|
2016-02-25 20:45:01 -08:00
|
|
|
your logging configuration file using the ``[DEFAULT] log_config_append``
|
|
|
|
option of ``keystone.conf``. If you wish to route all your logging through
|
|
|
|
syslog, set the ``[DEFAULT] use_syslog`` option.
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-02-25 20:45:01 -08:00
|
|
|
A sample ``log_config_append`` file is included with the project at
|
2016-10-17 18:11:15 -07:00
|
|
|
``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
|
2016-02-25 20:45:01 -08:00
|
|
|
`Python logging module`_, which includes extensive configuration options for
|
2012-01-29 10:57:02 -08:00
|
|
|
choosing the output levels and formats.
|
|
|
|
|
|
|
|
.. _Paste: http://pythonpaste.org/
|
2014-06-24 13:50:31 +00:00
|
|
|
.. _`Python logging module`: http://docs.python.org/library/logging.html
|
2012-01-24 09:43:06 -08:00
|
|
|
|
2012-05-23 18:05:11 +00:00
|
|
|
SSL
|
2016-11-18 13:46:23 -05:00
|
|
|
===
|
2012-05-23 18:05:11 +00:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
A secure deployment should have keystone running in a web server (such as
|
2016-04-17 01:56:08 -04:00
|
|
|
Apache httpd), or behind an SSL terminator.
|
2013-04-04 17:44:01 +10:00
|
|
|
|
2012-05-23 18:05:11 +00:00
|
|
|
|
2015-11-20 11:22:59 +08:00
|
|
|
OAuth1 1.0a
|
2016-11-18 13:46:23 -05:00
|
|
|
===========
|
2015-11-20 11:22:59 +08:00
|
|
|
|
|
|
|
The OAuth 1.0a feature provides the ability for Identity users to delegate
|
|
|
|
roles to third party consumers via the OAuth 1.0a specification.
|
|
|
|
|
|
|
|
To enable OAuth1:
|
|
|
|
|
2016-01-22 14:06:03 +00:00
|
|
|
1. Add the oauth1 driver to the ``[oauth1]`` section in ``keystone.conf``. For
|
|
|
|
example:
|
2015-11-20 11:22:59 +08:00
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[oauth1]
|
|
|
|
driver = sql
|
|
|
|
|
|
|
|
2. Add the ``oauth1`` authentication method to the ``[auth]`` section in
|
2016-01-22 14:06:03 +00:00
|
|
|
``keystone.conf``:
|
2015-11-20 11:22:59 +08:00
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[auth]
|
|
|
|
methods = external,password,token,oauth1
|
|
|
|
|
2016-01-22 14:06:03 +00:00
|
|
|
3. If deploying under Apache httpd with ``mod_wsgi``, set the
|
|
|
|
`WSGIPassAuthorization` to allow the OAuth Authorization headers to pass
|
|
|
|
through `mod_wsgi`. For example, add the following to the keystone virtual
|
|
|
|
host file:
|
2015-11-20 11:22:59 +08:00
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
WSGIPassAuthorization On
|
|
|
|
|
2017-05-01 21:15:02 +02:00
|
|
|
See `API Specification for OAuth 1.0a <https://developer.openstack.org/
|
|
|
|
api-ref/identity/v3-ext/index.html#os-oauth1-api>`_ for the details of
|
2015-11-20 11:22:59 +08:00
|
|
|
API definition.
|
|
|
|
|
|
|
|
|
|
|
|
Revocation Events
|
2016-11-18 13:46:23 -05:00
|
|
|
=================
|
2015-11-20 11:22:59 +08:00
|
|
|
|
|
|
|
The Revocation Events feature provides a list of token revocations. Each event
|
|
|
|
expresses a set of criteria which describes a set of tokens that are
|
|
|
|
no longer valid.
|
|
|
|
|
|
|
|
Add the revoke backend driver to the ``[revoke]`` section in
|
|
|
|
``keystone.conf``. For example:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[revoke]
|
|
|
|
driver = sql
|
|
|
|
|
2017-05-01 21:15:02 +02:00
|
|
|
See `API Specification for Revocation Events <https://developer.openstack.org/
|
|
|
|
api-ref/identity/v3-ext/index.html#os-revoke-api>`_ for
|
2015-11-20 11:22:59 +08:00
|
|
|
the details of API definition.
|
|
|
|
|
2013-07-05 06:04:25 +01:00
|
|
|
|
2013-06-17 04:22:06 +00:00
|
|
|
Token Binding
|
2016-11-18 13:46:23 -05:00
|
|
|
=============
|
2013-06-17 04:22:06 +00:00
|
|
|
|
|
|
|
Token binding refers to the practice of embedding information from external
|
|
|
|
authentication providers (like a company's Kerberos server) inside the token
|
|
|
|
such that a client may enforce that the token only be used in conjunction with
|
|
|
|
that specified authentication. This is an additional security mechanism as it
|
2015-01-09 23:51:12 -03:00
|
|
|
means that if a token is stolen it will not be usable without also providing
|
|
|
|
the external authentication.
|
2013-06-17 04:22:06 +00:00
|
|
|
|
|
|
|
To activate token binding you must specify the types of authentication that
|
2014-09-25 03:51:08 -04:00
|
|
|
token binding should be used for in ``keystone.conf`` e.g.:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-06-17 04:22:06 +00:00
|
|
|
|
|
|
|
[token]
|
|
|
|
bind = kerberos
|
|
|
|
|
|
|
|
Currently only ``kerberos`` is supported.
|
|
|
|
|
|
|
|
To enforce checking of token binding the ``enforce_token_bind`` parameter
|
|
|
|
should be set to one of the following modes:
|
|
|
|
|
|
|
|
* ``disabled`` disable token bind checking
|
|
|
|
* ``permissive`` enable bind checking, if a token is bound to a mechanism that
|
|
|
|
is unknown to the server then ignore it. This is the default.
|
|
|
|
* ``strict`` enable bind checking, if a token is bound to a mechanism that is
|
|
|
|
unknown to the server then this token should be rejected.
|
|
|
|
* ``required`` enable bind checking and require that at least 1 bind mechanism
|
|
|
|
is used for tokens.
|
|
|
|
* named enable bind checking and require that the specified authentication
|
2014-09-25 03:51:08 -04:00
|
|
|
mechanism is used. e.g.:
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
.. code-block:: ini
|
2013-06-17 04:22:06 +00:00
|
|
|
|
|
|
|
[token]
|
|
|
|
enforce_token_bind = kerberos
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
*Do not* set ``enforce_token_bind = named`` as there is not an authentication
|
|
|
|
mechanism called ``named``.
|
2013-06-17 04:22:06 +00:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Limiting list return size
|
|
|
|
=========================
|
2013-08-11 10:26:31 +01:00
|
|
|
|
|
|
|
Keystone provides a method of setting a limit to the number of entities
|
2014-02-11 11:26:47 -06:00
|
|
|
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
|
2015-01-09 23:51:12 -03:00
|
|
|
``keystone.conf``, with no limit set by default. Individual driver sections may
|
|
|
|
override this global value with a specific limit, for example:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-08-11 10:26:31 +01:00
|
|
|
|
2015-01-02 00:22:04 +00:00
|
|
|
[resource]
|
2013-08-11 10:26:31 +01:00
|
|
|
list_limit = 100
|
|
|
|
|
2014-02-11 11:26:47 -06:00
|
|
|
If a response to ``list_{entity}`` call has been truncated, then the response
|
2013-08-11 10:26:31 +01:00
|
|
|
status code will still be 200 (OK), but the ``truncated`` attribute in the
|
|
|
|
collection will be set to ``true``.
|
|
|
|
|
2015-12-13 00:15:34 +00:00
|
|
|
|
2016-02-25 20:45:01 -08:00
|
|
|
URL safe naming of projects and domains
|
2016-11-18 13:46:23 -05:00
|
|
|
=======================================
|
2015-12-13 00:15:34 +00:00
|
|
|
|
|
|
|
In the future, keystone may offer the ability to identify a project in a
|
2016-02-25 20:45:01 -08:00
|
|
|
hierarchy via a URL style of naming from the root of the hierarchy (for example
|
2015-12-13 00:15:34 +00:00
|
|
|
specifying 'projectA/projectB/projectC' as the project name in an
|
|
|
|
authentication request). In order to prepare for this, keystone supports the
|
|
|
|
optional ability to ensure both projects and domains are named without
|
2017-02-20 10:32:30 +08:00
|
|
|
including any of the reserved characters specified in section 2.2 of
|
2015-12-13 00:15:34 +00:00
|
|
|
`rfc3986 <http://tools.ietf.org/html/rfc3986>`_.
|
|
|
|
|
|
|
|
The safety of the names of projects and domains can be controlled via two
|
|
|
|
configuration options:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[resource]
|
|
|
|
project_name_url_safe = off
|
|
|
|
domain_name_url_safe = off
|
|
|
|
|
2016-02-25 20:45:01 -08:00
|
|
|
When set to ``off`` (which is the default), no checking is done on the URL
|
2015-12-13 00:15:34 +00:00
|
|
|
safeness of names. When set to ``new``, an attempt to create a new project or
|
|
|
|
domain with an unsafe name (or update the name of a project or domain to be
|
|
|
|
unsafe) will cause a status code of 400 (Bad Request) to be returned. Setting
|
|
|
|
the configuration option to ``strict`` will, in addition to preventing the
|
|
|
|
creation and updating of entities with unsafe names, cause an authentication
|
|
|
|
attempt which specifies a project or domain name that is unsafe to return a
|
|
|
|
status code of 401 (Unauthorized).
|
|
|
|
|
|
|
|
It is recommended that installations take the steps necessary to where they
|
|
|
|
can run with both options set to ``strict`` as soon as is practical.
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Health Check middleware
|
|
|
|
=======================
|
2016-10-17 17:20:54 -07:00
|
|
|
|
|
|
|
This health check middleware allows an operator to configure the endpoint URL
|
|
|
|
that will provide information to a load balancer if the given API endpoint at
|
|
|
|
the node should be available or not.
|
|
|
|
|
|
|
|
To enable the health check middleware, it must occur in the beginning of the
|
|
|
|
application pipeline.
|
|
|
|
|
|
|
|
The health check middleware should be placed in your
|
|
|
|
``keystone-paste.ini`` in a section titled ``[filter:healthcheck]``.
|
|
|
|
It should look like this::
|
|
|
|
|
|
|
|
[filter:healthcheck]
|
|
|
|
use = egg:oslo.middleware#healthcheck
|
|
|
|
|
|
|
|
Desired keystone application pipelines have been defined with this filter,
|
|
|
|
looking like so::
|
|
|
|
|
|
|
|
[pipeline:public_version_api]
|
|
|
|
pipeline = healthcheck cors sizelimit osprofiler url_normalize public_version_service
|
|
|
|
|
|
|
|
It's important that the healthcheck go to the front of the pipeline for the
|
|
|
|
most efficient checks.
|
|
|
|
|
|
|
|
For more information and configuration options for the middleware see
|
2017-01-30 13:53:09 -08:00
|
|
|
`oslo.middleware <https://docs.openstack.org/developer/oslo.middleware/api.html#oslo_middleware.Healthcheck>`_.
|
2016-10-17 17:20:54 -07:00
|
|
|
|
2014-02-10 11:50:31 +01:00
|
|
|
.. _`API protection with RBAC`:
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
API protection with Role Based Access Control (RBAC)
|
|
|
|
=====================================================
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Like most OpenStack projects, keystone supports the protection of its APIs by
|
2015-01-09 23:51:12 -03:00
|
|
|
defining policy rules based on an RBAC approach. These are stored in a JSON
|
2016-10-17 18:11:15 -07:00
|
|
|
policy file, the name and location of which is set in the main keystone
|
2014-02-10 11:50:31 +01:00
|
|
|
configuration file.
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Each keystone v3 API has a line in the policy file which dictates what level of
|
2015-01-09 23:51:12 -03:00
|
|
|
protection is applied to it, where each line is of the form::
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
<api name>: <rule statement> or <match statement>
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
where:
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
``<rule statement>`` can contain ``<rule statement>`` or ``<match statement>``
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
``<match statement>`` is a set of identifiers that must match between the token
|
2015-01-09 23:51:12 -03:00
|
|
|
provided by the caller of the API and the parameters or target entities of the
|
|
|
|
API call in question. For example:
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
.. code-block:: javascript
|
|
|
|
|
2015-02-11 18:51:52 -06:00
|
|
|
"identity:create_user": "role:admin and domain_id:%(user.domain_id)s"
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
Indicates that to create a user you must have the admin role in your token and
|
2014-02-10 11:50:31 +01:00
|
|
|
in addition the domain_id in your token (which implies this must be a domain
|
|
|
|
scoped token) must match the domain_id in the user object you are trying to
|
2015-01-09 23:51:12 -03:00
|
|
|
create. In other words, you must have the admin role on the domain in which you
|
|
|
|
are creating the user, and the token you are using must be scoped to that
|
2014-02-10 11:50:31 +01:00
|
|
|
domain.
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
Each component of a match statement is of the form::
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
<attribute from token>:<constant> or <attribute related to API call>
|
2014-02-10 11:50:31 +01:00
|
|
|
|
|
|
|
The following attributes are available
|
|
|
|
|
|
|
|
* Attributes from token: user_id, the domain_id or project_id depending on
|
|
|
|
the scope, and the list of roles you have within that scope
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
* Attributes related to API call: Any parameters that are passed into the API
|
|
|
|
call are available, along with any filters specified in the query string.
|
|
|
|
Attributes of objects passed can be referenced using an object.attribute
|
|
|
|
syntax (e.g. user.domain_id). The target objects of an API are also available
|
|
|
|
using a target.object.attribute syntax. For instance:
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
.. code-block:: javascript
|
|
|
|
|
2015-02-11 18:51:52 -06:00
|
|
|
"identity:delete_user": "role:admin and domain_id:%(target.user.domain_id)s"
|
2014-02-10 11:50:31 +01:00
|
|
|
|
|
|
|
would ensure that the user object that is being deleted is in the same
|
|
|
|
domain as the token provided.
|
|
|
|
|
2015-05-12 11:37:53 +08:00
|
|
|
Every target object (except token) has an `id` and a `name` available as
|
|
|
|
`target.<object>.id` and `target.<object>.name`. Other attributes are retrieved
|
|
|
|
from the database and vary between object types. Moreover, some database fields
|
|
|
|
are filtered out (e.g. user passwords).
|
2014-02-10 11:50:31 +01:00
|
|
|
|
|
|
|
List of object attributes:
|
|
|
|
|
|
|
|
* role:
|
2015-12-28 21:31:34 +00:00
|
|
|
* target.role.domain_id
|
2014-02-10 11:50:31 +01:00
|
|
|
* target.role.id
|
|
|
|
* target.role.name
|
|
|
|
|
|
|
|
* user:
|
|
|
|
* target.user.default_project_id
|
|
|
|
* target.user.description
|
|
|
|
* target.user.domain_id
|
|
|
|
* target.user.enabled
|
|
|
|
* target.user.id
|
|
|
|
* target.user.name
|
2016-09-07 17:04:21 -07:00
|
|
|
* target.user.password_expires_at
|
2014-02-10 11:50:31 +01:00
|
|
|
|
|
|
|
* group:
|
|
|
|
* target.group.description
|
|
|
|
* target.group.domain_id
|
|
|
|
* target.group.id
|
|
|
|
* target.group.name
|
|
|
|
|
|
|
|
* domain:
|
2016-09-07 17:04:21 -07:00
|
|
|
* target.domain.description
|
2014-02-10 11:50:31 +01:00
|
|
|
* target.domain.enabled
|
|
|
|
* target.domain.id
|
|
|
|
* target.domain.name
|
|
|
|
|
|
|
|
* project:
|
|
|
|
* target.project.description
|
|
|
|
* target.project.domain_id
|
|
|
|
* target.project.enabled
|
|
|
|
* target.project.id
|
2016-09-07 17:04:21 -07:00
|
|
|
* target.project.is_domain
|
2014-02-10 11:50:31 +01:00
|
|
|
* target.project.name
|
2016-09-07 17:04:21 -07:00
|
|
|
* target.project.parent_id
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2015-05-12 11:37:53 +08:00
|
|
|
* token
|
|
|
|
* target.token.user_id
|
|
|
|
* target.token.user.domain.id
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
The default policy.json file supplied provides a somewhat basic example of API
|
|
|
|
protection, and does not assume any particular use of domains. For multi-domain
|
|
|
|
configuration installations where, for example, a cloud provider wishes to
|
|
|
|
allow administration of the contents of a domain to be delegated, it is
|
|
|
|
recommended that the supplied policy.v3cloudsample.json is used as a basis for
|
|
|
|
creating a suitable production policy file. This example policy file also shows
|
|
|
|
the use of an admin_domain to allow a cloud provider to enable cloud
|
|
|
|
administrators to have wider access across the APIs.
|
|
|
|
|
|
|
|
A clean installation would need to perhaps start with the standard policy file,
|
|
|
|
to allow creation of the admin_domain with the first users within it. The
|
|
|
|
domain_id of the admin domain would then be obtained and could be pasted into a
|
|
|
|
modified version of policy.v3cloudsample.json which could then be enabled as
|
|
|
|
the main policy file.
|
2014-02-10 11:50:31 +01:00
|
|
|
|
2012-12-04 15:11:16 -05:00
|
|
|
.. _`prepare your deployment`:
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2012-12-04 15:11:16 -05:00
|
|
|
Preparing your deployment
|
|
|
|
=========================
|
2012-03-01 12:31:53 -06:00
|
|
|
|
|
|
|
Step 1: Configure keystone.conf
|
|
|
|
-------------------------------
|
|
|
|
|
2014-09-25 03:51:08 -04:00
|
|
|
Ensure that your ``keystone.conf`` is configured to use a SQL driver:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-02-02 20:40:39 -08:00
|
|
|
|
2012-03-01 12:31:53 -06:00
|
|
|
[identity]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = sql
|
2012-02-02 20:40:39 -08:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
You may also want to configure your ``[database]`` settings to better reflect
|
|
|
|
your environment:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-02-02 20:40:39 -08:00
|
|
|
|
2014-10-09 15:39:27 +08:00
|
|
|
[database]
|
2012-03-01 12:31:53 -06:00
|
|
|
connection = sqlite:///keystone.db
|
|
|
|
idle_timeout = 200
|
2012-02-02 20:40:39 -08:00
|
|
|
|
2012-03-01 12:31:53 -06:00
|
|
|
.. NOTE::
|
|
|
|
|
|
|
|
It is important that the database that you specify be different from the
|
|
|
|
one containing your existing install.
|
|
|
|
|
|
|
|
Step 2: Sync your new, empty database
|
|
|
|
-------------------------------------
|
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
You should now be ready to initialize your new database without error, using:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-03-01 12:31:53 -06:00
|
|
|
|
|
|
|
$ keystone-manage db_sync
|
|
|
|
|
2016-05-10 10:15:00 -05:00
|
|
|
To test this, you should now be able to start keystone:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ uwsgi --http 127.0.0.1:35357 --wsgi-file $(which keystone-wsgi-admin)
|
|
|
|
|
|
|
|
And use the OpenStack Client to list your projects (which should successfully
|
|
|
|
return an empty list from your new database):
|
2014-09-04 17:08:07 -04:00
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2014-09-26 00:58:00 -04:00
|
|
|
$ openstack --os-token ADMIN --os-url http://127.0.0.1:35357/v2.0/ project list
|
2012-03-01 12:31:53 -06:00
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
We're providing the default OS_TOKEN and OS_URL values from
|
2016-10-17 18:11:15 -07:00
|
|
|
``keystone.conf`` to connect to the keystone service. If you changed those
|
|
|
|
values, or deployed keystone to a different endpoint, you will need to
|
2015-01-09 23:51:12 -03:00
|
|
|
change the provided command accordingly.
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
``keystone-manage``
|
|
|
|
===================
|
2014-09-26 00:58:00 -04:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
``keystone-manage`` is the command line tool which interacts with the Keystone
|
|
|
|
service to initialize and update data within Keystone. Generally,
|
|
|
|
``keystone-manage`` is only used for operations that cannot be accomplished
|
|
|
|
with the HTTP API, such data import/export and database migrations.
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
.. include:: man/commands.rst
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Removing Expired Tokens
|
|
|
|
=======================
|
2012-03-26 10:27:15 -07:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
In the SQL backend expired UUID tokens are not automatically removed. These
|
|
|
|
tokens can be removed with:
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
.. code-block:: bash
|
2012-01-29 10:57:02 -08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
$ keystone-manage token_flush
|
2012-01-29 14:09:24 -08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
It is recommended to run this command periodically with ``cron`` if using UUID
|
|
|
|
tokens.
|
2012-02-14 12:30:23 -08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
.. NOTE::
|
2014-09-04 17:08:07 -04:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
It it not required to run this command at all if using Fernet tokens. Fernet
|
|
|
|
tokens are not persisted.
|
2012-02-14 12:30:23 -08:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Supported clients
|
|
|
|
=================
|
2014-09-26 00:58:00 -04:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
There are two supported clients, `python-keystoneclient`_ project provides
|
|
|
|
python bindings and `python-openstackclient`_ provides a command line
|
|
|
|
interface.
|
2014-09-26 00:58:00 -04:00
|
|
|
|
2017-01-30 13:53:09 -08:00
|
|
|
.. _`python-openstackclient`: https://docs.openstack.org/developer/python-openstackclient/
|
|
|
|
.. _`python-keystoneclient`: https://docs.openstack.org/developer/python-keystoneclient/
|
2014-09-26 00:58:00 -04:00
|
|
|
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Authenticating with a Password via CLI
|
|
|
|
--------------------------------------
|
2012-03-01 12:31:53 -06:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
To authenticate with keystone using a password and ``python-openstackclient``,
|
2015-01-09 23:51:12 -03:00
|
|
|
set the following flags, note that the following user referenced below should
|
2012-03-01 12:31:53 -06:00
|
|
|
be granted the ``admin`` role.
|
|
|
|
|
2014-09-26 00:58:00 -04:00
|
|
|
* ``--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
|
2016-10-17 18:11:15 -07:00
|
|
|
* ``--os-auth-url OS_AUTH_URL``: URL of the keystone authentication server
|
2012-03-01 12:31:53 -06:00
|
|
|
|
|
|
|
You can also set these variables in your environment so that they do not need
|
2014-09-04 17:08:07 -04:00
|
|
|
to be passed as arguments each time:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-03-01 12:31:53 -06:00
|
|
|
|
|
|
|
$ export OS_USERNAME=my_username
|
|
|
|
$ export OS_PASSWORD=my_password
|
2014-09-26 00:58:00 -04:00
|
|
|
$ export OS_PROJECT_NAME=my_project
|
|
|
|
$ export OS_AUTH_URL=http://localhost:35357/v2.0
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
For example, the commands ``user list``, ``token issue`` and ``project create``
|
|
|
|
can be invoked as follows:
|
2014-08-27 13:17:03 -04:00
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-02-14 12:30:23 -08:00
|
|
|
|
2014-09-26 00:58:00 -04:00
|
|
|
# Using password authentication, with environment variables
|
2014-08-27 13:17:03 -04:00
|
|
|
$ export OS_USERNAME=admin
|
2016-12-08 13:07:29 +00:00
|
|
|
$ export OS_PASSWORD=secret
|
2014-09-26 00:58:00 -04:00
|
|
|
$ export OS_PROJECT_NAME=admin
|
|
|
|
$ export OS_AUTH_URL=http://localhost:35357/v2.0
|
|
|
|
$ openstack user list
|
|
|
|
$ openstack project create demo
|
2016-11-18 13:46:23 -05:00
|
|
|
$ openstack token issue
|
2012-02-14 12:30:23 -08:00
|
|
|
|
2014-09-26 00:58:00 -04:00
|
|
|
# Using password authentication, with flags
|
2016-12-08 13:07:29 +00:00
|
|
|
$ openstack --os-username=admin --os-password=secret --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 user list
|
|
|
|
$ openstack --os-username=admin --os-password=secret --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 project create demo
|
2012-01-29 10:57:02 -08:00
|
|
|
|
2014-09-04 17:08:07 -04:00
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
Using an LDAP server
|
|
|
|
====================
|
2012-03-07 16:04:32 -05:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
As an alternative to the SQL Database backing store, keystone can use a
|
|
|
|
directory server to provide the Identity service. An example schema for
|
2015-01-09 23:51:12 -03:00
|
|
|
OpenStack would look like this::
|
2012-03-07 16:04:32 -05:00
|
|
|
|
2013-06-13 12:40:36 -05:00
|
|
|
dn: dc=openstack,dc=org
|
2012-03-07 16:04:32 -05:00
|
|
|
dc: openstack
|
|
|
|
objectClass: dcObject
|
|
|
|
objectClass: organizationalUnit
|
|
|
|
ou: openstack
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
dn: ou=Groups,dc=openstack,dc=org
|
2012-03-07 16:04:32 -05:00
|
|
|
objectClass: top
|
|
|
|
objectClass: organizationalUnit
|
|
|
|
ou: groups
|
|
|
|
|
2013-06-13 12:40:36 -05:00
|
|
|
dn: ou=Users,dc=openstack,dc=org
|
2012-03-07 16:04:32 -05:00
|
|
|
objectClass: top
|
|
|
|
objectClass: organizationalUnit
|
|
|
|
ou: users
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
The corresponding entries in the keystone configuration file are:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-03-07 16:04:32 -05:00
|
|
|
|
|
|
|
[ldap]
|
|
|
|
url = ldap://localhost
|
|
|
|
user = dc=Manager,dc=openstack,dc=org
|
|
|
|
password = badpassword
|
2012-10-29 15:07:58 +01:00
|
|
|
suffix = dc=openstack,dc=org
|
|
|
|
|
2013-06-13 12:40:36 -05:00
|
|
|
user_tree_dn = ou=Users,dc=openstack,dc=org
|
2012-10-29 15:07:58 +01:00
|
|
|
user_objectclass = inetOrgPerson
|
|
|
|
|
2015-01-09 23:11:15 -03:00
|
|
|
The default object classes and attributes are intentionally simplistic. They
|
2015-01-09 23:51:12 -03:00
|
|
|
reflect the common standard objects according to the LDAP RFCs. However, in a
|
|
|
|
live deployment, the correct attributes can be overridden to support a
|
2015-01-09 23:11:15 -03:00
|
|
|
preexisting, more complex schema. For example, in the user object, the
|
2015-01-09 23:51:12 -03:00
|
|
|
objectClass posixAccount from RFC2307 is very common. If this is the underlying
|
|
|
|
objectclass, then the *uid* field should probably be *uidNumber* and *username*
|
|
|
|
field either *uid* or *cn*. To change these two fields, the corresponding
|
2016-10-17 18:11:15 -07:00
|
|
|
entries in the keystone configuration file are:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-07-26 15:30:39 -04:00
|
|
|
|
|
|
|
[ldap]
|
|
|
|
user_id_attribute = uidNumber
|
|
|
|
user_name_attribute = cn
|
2012-10-29 15:07:58 +01:00
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
There are some configuration options for filtering users, tenants and roles, if
|
|
|
|
the backend is providing too much output, in such case the configuration will
|
|
|
|
look like:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-04-04 17:44:01 +10:00
|
|
|
|
2012-10-29 15:07:58 +01:00
|
|
|
[ldap]
|
2013-07-11 09:15:38 -05:00
|
|
|
user_filter = (memberof=CN=openstack-users,OU=workgroups,DC=openstack,DC=org)
|
2012-10-29 15:07:58 +01:00
|
|
|
|
|
|
|
In case that the directory server does not have an attribute enabled of type
|
2015-01-09 23:51:12 -03:00
|
|
|
boolean for the user, there is several configuration parameters that can be
|
|
|
|
used to extract the value from an integer attribute like in Active Directory:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-10-29 15:07:58 +01:00
|
|
|
|
|
|
|
[ldap]
|
|
|
|
user_enabled_attribute = userAccountControl
|
|
|
|
user_enabled_mask = 2
|
|
|
|
user_enabled_default = 512
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
In this case the attribute is an integer and the enabled attribute is listed in
|
|
|
|
bit 1, so the if the mask configured *user_enabled_mask* is different from 0,
|
2012-10-29 15:07:58 +01:00
|
|
|
it gets the value from the field *user_enabled_attribute* and it makes an ADD
|
2015-01-09 23:51:12 -03:00
|
|
|
operation with the value indicated on *user_enabled_mask* and if the value
|
|
|
|
matches the mask then the account is disabled.
|
2012-10-29 15:07:58 +01:00
|
|
|
|
|
|
|
It also saves the value without mask to the user identity in the attribute
|
2015-01-09 23:51:12 -03:00
|
|
|
*enabled_nomask*. This is needed in order to set it back in case that we need
|
|
|
|
to change it to enable/disable a user because it contains more information than
|
|
|
|
the status like password expiration. Last setting *user_enabled_mask* is needed
|
|
|
|
in order to create a default value on the integer attribute (512 = NORMAL
|
|
|
|
ACCOUNT on AD)
|
2012-10-29 15:07:58 +01:00
|
|
|
|
|
|
|
In case of Active Directory the classes and attributes could not match the
|
2014-09-25 03:51:08 -04:00
|
|
|
specified classes in the LDAP module so you can configure them like:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2012-10-29 15:07:58 +01:00
|
|
|
|
|
|
|
[ldap]
|
2016-02-05 19:58:53 +01:00
|
|
|
user_objectclass = person
|
|
|
|
user_id_attribute = cn
|
|
|
|
user_name_attribute = cn
|
|
|
|
user_description_attribute = displayName
|
|
|
|
user_mail_attribute = mail
|
|
|
|
user_enabled_attribute = userAccountControl
|
|
|
|
user_enabled_mask = 2
|
|
|
|
user_enabled_default = 512
|
|
|
|
user_attribute_ignore = tenant_id,tenants
|
2013-03-25 15:23:15 -05:00
|
|
|
|
2014-05-21 11:19:16 -06:00
|
|
|
Debugging LDAP
|
|
|
|
--------------
|
|
|
|
|
|
|
|
For additional information on LDAP connections, performance (such as slow
|
|
|
|
response time), or field mappings, setting ``debug_level`` in the [ldap]
|
2014-09-25 03:51:08 -04:00
|
|
|
section is used to enable debugging:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
2014-05-21 11:19:16 -06:00
|
|
|
|
|
|
|
debug_level = 4095
|
|
|
|
|
|
|
|
This setting in turn sets OPT_DEBUG_LEVEL in the underlying python library.
|
2015-01-09 23:51:12 -03:00
|
|
|
This field is a bit mask (integer), and the possible flags are documented in
|
|
|
|
the OpenLDAP manpages. Commonly used values include 255 and 4095, with 4095
|
|
|
|
being more verbose.
|
2014-05-21 11:19:16 -06:00
|
|
|
|
|
|
|
.. WARNING::
|
|
|
|
Enabling ``debug_level`` will negatively impact performance.
|
2014-02-03 13:22:51 -07:00
|
|
|
|
|
|
|
Enabled Emulation
|
|
|
|
-----------------
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Some directory servers do not provide any enabled attribute. For these servers,
|
2016-01-20 15:30:32 -08:00
|
|
|
the ``user_enabled_emulation`` attribute has been created. It is enabled by
|
|
|
|
setting the respective flags to True. Then the attribute
|
|
|
|
``user_enabled_emulation_dn`` may be set to specify how the enabled users are
|
|
|
|
selected. This attribute works by using a ``groupOfNames`` entry and adding
|
|
|
|
whichever users or that you want enabled to the respective group with the
|
|
|
|
``member`` attribute. For example, this will mark any user who is a member of
|
|
|
|
``enabled_users`` as enabled:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2014-02-03 13:22:51 -07:00
|
|
|
|
|
|
|
[ldap]
|
|
|
|
user_enabled_emulation = True
|
|
|
|
user_enabled_emulation_dn = cn=enabled_users,cn=groups,dc=openstack,dc=org
|
|
|
|
|
2016-01-20 15:30:32 -08:00
|
|
|
The default values for user enabled emulation DN is
|
|
|
|
``cn=enabled_users,$user_tree_dn``.
|
|
|
|
|
2014-02-03 13:22:51 -07:00
|
|
|
|
2015-11-11 07:56:48 -08:00
|
|
|
If a different LDAP schema is used for group membership, it is possible to use
|
|
|
|
the ``group_objectclass`` and ``group_member_attribute`` attributes to
|
|
|
|
determine membership in the enabled emulation group by setting the
|
2016-01-20 15:30:32 -08:00
|
|
|
``user_enabled_emulation_use_group_config`` attribute to True.
|
2015-11-11 07:56:48 -08:00
|
|
|
|
2014-02-03 13:22:51 -07:00
|
|
|
Secure Connection
|
|
|
|
-----------------
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
If you are using a directory server to provide the Identity service, it is
|
2016-10-17 18:11:15 -07:00
|
|
|
strongly recommended that you utilize a secure connection from keystone to the
|
|
|
|
directory server. In addition to supporting LDAP, keystone also provides
|
2015-01-09 23:51:12 -03:00
|
|
|
Transport Layer Security (TLS) support. There are some basic configuration
|
|
|
|
options for enabling TLS, identifying a single file or directory that contains
|
2016-10-17 18:11:15 -07:00
|
|
|
certificates for all the Certificate Authorities that the keystone LDAP client
|
2015-01-09 23:51:12 -03:00
|
|
|
will recognize, and declaring what checks the client should perform on server
|
|
|
|
certificates. This functionality can easily be configured as follows:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-03-25 15:23:15 -05:00
|
|
|
|
|
|
|
[ldap]
|
|
|
|
use_tls = True
|
|
|
|
tls_cacertfile = /etc/keystone/ssl/certs/cacert.pem
|
|
|
|
tls_cacertdir = /etc/keystone/ssl/certs/
|
|
|
|
tls_req_cert = demand
|
|
|
|
|
2015-01-09 23:11:15 -03:00
|
|
|
A few points worth mentioning regarding the above options. If both
|
2016-10-17 18:11:15 -07:00
|
|
|
``tls_cacertfile`` and ``tls_cacertdir`` are set then tls_cacertfile will be
|
|
|
|
used and ``tls_cacertdir`` is ignored. Furthermore, valid options for
|
|
|
|
``tls_req_cert`` are ``demand``, ``never``, and ``allow``. These correspond to
|
|
|
|
the standard options permitted by the ``TLS_REQCERT`` TLS option.
|
2013-11-12 14:50:19 -06:00
|
|
|
|
2016-09-29 15:27:34 +05:30
|
|
|
.. NOTE::
|
|
|
|
|
2016-11-18 13:46:23 -05:00
|
|
|
If unable to connect to LDAP via keystone (more specifically, if a
|
|
|
|
*SERVER DOWN* error is seen), set the ``TLS_CACERT`` in
|
|
|
|
``/etc/ldap/ldap.conf`` to the same value specified in the
|
|
|
|
``[ldap] tls_certificate`` section of ``keystone.conf``.
|
2016-09-29 15:27:34 +05:30
|
|
|
|
2013-11-12 14:50:19 -06:00
|
|
|
Read Only LDAP
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Many environments typically have user and group information in directories that
|
2014-01-23 16:24:09 +08:00
|
|
|
are accessible by LDAP. This information is for read-only use in a wide array
|
2016-10-17 18:11:15 -07:00
|
|
|
of applications. Prior to the Havana release, we could not deploy keystone with
|
|
|
|
read-only directories as backends because keystone also needed to store
|
2013-11-12 14:50:19 -06:00
|
|
|
information such as projects, roles, domains and role assignments into the
|
|
|
|
directories in conjunction with reading user and group information.
|
|
|
|
|
2015-01-09 23:51:12 -03:00
|
|
|
Keystone now provides an option whereby these read-only directories can be
|
|
|
|
easily integrated as it now enables its identity entities (which comprises
|
|
|
|
users, groups, and group memberships) to be served out of directories while
|
2015-01-02 00:22:04 +00:00
|
|
|
resource (which comprises projects and domains), assignment and role
|
2016-10-17 18:11:15 -07:00
|
|
|
entities are to be served from different keystone backends (i.e. SQL). To
|
2015-01-02 00:22:04 +00:00
|
|
|
enable this option, you must have the following ``keystone.conf`` options set:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2013-11-12 14:50:19 -06:00
|
|
|
|
|
|
|
[identity]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = ldap
|
2013-11-12 14:50:19 -06:00
|
|
|
|
2015-01-02 00:22:04 +00:00
|
|
|
[resource]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = sql
|
2015-01-02 00:22:04 +00:00
|
|
|
|
2013-11-12 14:50:19 -06:00
|
|
|
[assignment]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = sql
|
2013-11-12 14:50:19 -06:00
|
|
|
|
2014-12-28 17:12:59 +00:00
|
|
|
[role]
|
2015-08-07 14:24:41 -05:00
|
|
|
driver = sql
|
2014-12-28 17:12:59 +00:00
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
With the above configuration, keystone will only lookup identity related
|
2015-01-09 23:51:12 -03:00
|
|
|
information such users, groups, and group membership from the directory, while
|
2015-01-02 00:22:04 +00:00
|
|
|
resources, roles and assignment related information will be provided by the SQL
|
|
|
|
backend. Also note that if there is an LDAP Identity, and no resource,
|
|
|
|
assignment or role backend is specified, they will default to LDAP. Although
|
2015-07-24 18:03:16 +09:00
|
|
|
this may seem counter intuitive, it is provided for backwards compatibility.
|
2015-01-02 00:22:04 +00:00
|
|
|
Nonetheless, the explicit option will always override the implicit option, so
|
2017-01-20 20:47:37 -05:00
|
|
|
specifying the options as shown above will always be correct.
|
2014-05-23 15:25:38 -07:00
|
|
|
|
2015-02-01 10:07:42 +00:00
|
|
|
.. NOTE::
|
|
|
|
|
2015-07-24 18:03:16 +09:00
|
|
|
While having identity related information backed by LDAP while other
|
2015-02-01 10:07:42 +00:00
|
|
|
information is backed by SQL is a supported configuration, as shown above;
|
|
|
|
the opposite is not true. If either resource or assignment drivers are
|
|
|
|
configured for LDAP, then Identity must also be configured for LDAP.
|
|
|
|
|
2014-05-23 15:25:38 -07:00
|
|
|
Connection Pooling
|
|
|
|
------------------
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
Various LDAP backends in keystone use a common LDAP module to interact with
|
2015-08-08 21:27:36 -07:00
|
|
|
LDAP data. By default, a new connection is established for each LDAP operation.
|
|
|
|
This can become highly expensive when TLS support is enabled, which is a likely
|
|
|
|
configuration in an enterprise setup. Reuse of connectors from a connection
|
|
|
|
pool drastically reduces overhead of initiating a new connection for every LDAP
|
2015-01-09 23:51:12 -03:00
|
|
|
operation.
|
2014-05-23 15:25:38 -07:00
|
|
|
|
2015-08-08 21:27:36 -07:00
|
|
|
Keystone provides connection pool support via configuration. This will keep
|
|
|
|
LDAP connectors alive and reused for subsequent LDAP operations. The connection
|
|
|
|
lifespan is configurable as other pooling specific attributes.
|
|
|
|
|
2016-10-17 18:11:15 -07:00
|
|
|
In the LDAP identity driver, keystone authenticates end users via an LDAP bind
|
2015-08-08 21:27:36 -07:00
|
|
|
with the user's DN and provided password. This kind of authentication bind
|
|
|
|
can fill up the pool pretty quickly, so a separate pool is provided for end
|
|
|
|
user authentication bind calls. If a deployment does not want to use a pool for
|
|
|
|
those binds, then it can disable pooling selectively by setting
|
2016-01-22 14:06:03 +00:00
|
|
|
``use_auth_pool`` to false. If a deployment wants to use a pool for those
|
2015-08-08 21:27:36 -07:00
|
|
|
authentication binds, then ``use_auth_pool`` needs to be set to true. For the
|
|
|
|
authentication pool, a different pool size (``auth_pool_size``) and connection
|
|
|
|
lifetime (``auth_pool_connection_lifetime``) can be specified. With an enabled
|
|
|
|
authentication pool, its connection lifetime should be kept short so that the
|
|
|
|
pool frequently re-binds the connection with the provided credentials and works
|
|
|
|
reliably in the end user password change case. When ``use_pool`` is false
|
|
|
|
(disabled), then the authentication pool configuration is also not used.
|
|
|
|
|
|
|
|
Connection pool configuration is part of the ``[ldap]`` configuration section:
|
2014-09-25 03:51:08 -04:00
|
|
|
|
|
|
|
.. code-block:: ini
|
2014-05-23 15:25:38 -07:00
|
|
|
|
|
|
|
[ldap]
|
2016-10-17 18:11:15 -07:00
|
|
|
# Enable LDAP connection pooling for queries to the LDAP server. There is
|
|
|
|
# typically no reason to disable this. (boolean value)
|
|
|
|
use_pool = true
|
|
|
|
|
|
|
|
# The size of the LDAP connection pool. This option has no effect unless
|
|
|
|
# `[ldap] use_pool` is also enabled. (integer value)
|
|
|
|
# Minimum value: 1
|
|
|
|
pool_size = 10
|
|
|
|
|
|
|
|
# The maximum number of times to attempt reconnecting to the LDAP server before
|
|
|
|
# aborting. A value of zero prevents retries. This option has no effect unless
|
|
|
|
# `[ldap] use_pool` is also enabled. (integer value)
|
|
|
|
# Minimum value: 0
|
|
|
|
pool_retry_max = 3
|
|
|
|
|
|
|
|
# The number of seconds to wait before attempting to reconnect to the LDAP
|
|
|
|
# server. This option has no effect unless `[ldap] use_pool` is also enabled.
|
2014-05-23 15:25:38 -07:00
|
|
|
# (floating point value)
|
2016-10-17 18:11:15 -07:00
|
|
|
pool_retry_delay = 0.1
|
|
|
|
|
|
|
|
# The connection timeout to use with the LDAP server. A value of `-1` means
|
|
|
|
# that connections will never timeout. This option has no effect unless `[ldap]
|
|
|
|
# use_pool` is also enabled. (integer value)
|
|
|
|
# Minimum value: -1
|
|
|
|
pool_connection_timeout = -1
|
|
|
|
|
|
|
|
# The maximum connection lifetime to the LDAP server in seconds. When this
|
|
|
|
# lifetime is exceeded, the connection will be unbound and removed from the
|
|
|
|
# connection pool. This option has no effect unless `[ldap] use_pool` is also
|
|
|
|
# enabled. (integer value)
|
|
|
|
# Minimum value: 1
|
|
|
|
pool_connection_lifetime = 600
|
|
|
|
|
|
|
|
# Enable LDAP connection pooling for end user authentication. There is
|
|
|
|
# typically no reason to disable this. (boolean value)
|
|
|
|
use_auth_pool = true
|
|
|
|
|
|
|
|
# The size of the connection pool to use for end user authentication. This
|
|
|
|
# option has no effect unless `[ldap] use_auth_pool` is also enabled. (integer
|
|
|
|
# value)
|
|
|
|
# Minimum value: 1
|
|
|
|
auth_pool_size = 100
|
|
|
|
|
|
|
|
# The maximum end user authentication connection lifetime to the LDAP server in
|
|
|
|
# seconds. When this lifetime is exceeded, the connection will be unbound and
|
|
|
|
# removed from the connection pool. This option has no effect unless `[ldap]
|
|
|
|
# use_auth_pool` is also enabled. (integer value)
|
|
|
|
# Minimum value: 1
|
|
|
|
auth_pool_connection_lifetime = 60
|
2014-05-23 15:25:38 -07:00
|
|
|
|
2016-02-07 02:54:08 -05:00
|
|
|
Specifying Multiple LDAP servers
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
Multiple LDAP server URLs can be provided to keystone to provide
|
|
|
|
high-availability support for a single LDAP backend. To specify multiple LDAP
|
|
|
|
servers, simply change the ``url`` option in the ``[ldap]`` section. The new
|
|
|
|
option should list the different servers, each separated by a comma. For
|
|
|
|
example:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[ldap]
|
|
|
|
url = "ldap://localhost,ldap://backup.localhost"
|
2016-08-12 03:22:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
Credential Encryption
|
|
|
|
=====================
|
|
|
|
|
|
|
|
As of the Newton release, keystone encrypts all credentials stored in the
|
|
|
|
default ``sql`` backend. Credentials are encrypted with the same mechanism used
|
|
|
|
to encrypt Fernet tokens, ``fernet``. Keystone provides only one type of
|
|
|
|
credential encryption but the encryption provider is pluggable in the event
|
|
|
|
you wish to supply a custom implementation.
|
|
|
|
|
|
|
|
This document details how credential encryption works, how to migrate existing
|
|
|
|
credentials in a deployment, and how to manage encryption keys for credentials.
|
|
|
|
|
|
|
|
Configuring credential encryption
|
|
|
|
---------------------------------
|
|
|
|
|
|
|
|
The configuration for credential encryption is straightforward. There are only
|
|
|
|
two configuration options needed:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[credential]
|
|
|
|
provider = fernet
|
|
|
|
key_repository = /etc/keystone/credential-keys/
|
|
|
|
|
|
|
|
``[credential] provider`` defaults to the only option supplied by keystone,
|
|
|
|
``fernet``. There is no reason to change this option unless you wish to provide
|
|
|
|
a custom credential encryption implementation. The ``[credential]
|
|
|
|
key_repository`` location is a requirement of using ``fernet`` but will default
|
|
|
|
to the ``/etc/keystone/credential-keys/`` directory. Both ``[credential]
|
|
|
|
key_repository`` and ``[fernet_tokens] key_repository`` define locations for
|
|
|
|
keys used to encrypt things. One holds the keys to encrypt and decrypt
|
|
|
|
credentials and the other holds keys to encrypt and decrypt tokens. It is
|
|
|
|
imperative that these repositories are managed separately and they must not
|
|
|
|
share keys. Meaning they cannot share the same directory path. The
|
|
|
|
``[credential] key_repository`` is only allowed to have three keys. This is not
|
|
|
|
configurable and allows for credentials to be re-encrypted periodically with a
|
|
|
|
new encryption key for the sake of security.
|
|
|
|
|
|
|
|
How credential encryption works
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
The implementation of this feature did not change any existing credential API
|
|
|
|
contracts. All changes are transparent to the user unless you're inspecting the
|
|
|
|
credential backend directly.
|
|
|
|
|
|
|
|
When creating a credential, keystone will encrypt the ``blob`` attribute before
|
|
|
|
persisting it to the backend. Keystone will also store a hash of the key that
|
|
|
|
was used to encrypt the information in that credential. Since Fernet is used to
|
|
|
|
encrypt credentials, a key repository consists of multiple keys. Keeping track
|
|
|
|
of which key was used to encrypt each credential is an important part of
|
|
|
|
encryption key management. Why this is important is detailed later in the
|
|
|
|
`Encryption key management` section.
|
|
|
|
|
|
|
|
When updating an existing credential's ``blob`` attribute, keystone will encrypt
|
|
|
|
the new ``blob`` and update the key hash.
|
|
|
|
|
|
|
|
When listing or showing credentials, all ``blob`` attributes are decrypted in
|
|
|
|
the response. Neither the cipher text, nor the hash of the key used to encrypt
|
|
|
|
the ``blob`` are exposed through the API. Furthermore, the key is only used
|
|
|
|
internally to keystone.
|
|
|
|
|
|
|
|
Encrypting existing credentials
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
When upgrading a Mitaka deployment to Newton, three database migrations will
|
|
|
|
ensure all credentials are encrypted. The process is as follows:
|
|
|
|
|
|
|
|
1. An additive schema change is made to create the new ``encrypted_blob`` and
|
|
|
|
``key_hash`` columns in the existing ``credential`` table using
|
|
|
|
``keystone-manage db_sync --expand``.
|
|
|
|
2. A data migration will loop through all existing credentials, encrypt each
|
|
|
|
``blob`` and store the result in the new ``encrypted_blob`` column. The hash
|
|
|
|
of the key used is also written to the ``key_hash`` column for that specific
|
|
|
|
credential. This step is done using ``keystone-manage db_sync --migrate``.
|
|
|
|
3. A contractive schema will remove the ``blob`` column that held the plain
|
|
|
|
text representations of the credential using ``keystone-manage db_sync
|
|
|
|
--contract``. This should only be done after all nodes in the deployment are
|
|
|
|
running Newton. If any Mitaka nodes are running after the database is
|
|
|
|
contracted, they won't be able to read credentials since they are looking
|
|
|
|
for the ``blob`` column that no longer exists.
|
|
|
|
|
2017-03-24 17:23:09 +00:00
|
|
|
.. NOTE::
|
|
|
|
|
|
|
|
You may also use ``keystone-manage db_sync --check`` in order to check the
|
|
|
|
current status of your rolling upgrades.
|
|
|
|
|
2016-08-12 03:22:56 +00:00
|
|
|
If performing a rolling upgrade, please note that a limited service outage will
|
|
|
|
take affect during this migration. When the migration is in place, credentials
|
|
|
|
will become read-only until the database is contracted. After the contract
|
|
|
|
phase is complete, credentials will be writeable to the backend. A
|
|
|
|
``[credential] key_repository`` location must be specified through
|
|
|
|
configuration and bootstrapped with keys using ``keystone-manage
|
2016-09-07 16:15:03 +00:00
|
|
|
credential_setup`` prior to migrating any existing credentials. If a new key
|
|
|
|
repository isn't setup using ``keystone-manage credential_setup`` keystone will
|
|
|
|
assume a null key to encrypt and decrypt credentials until a proper key
|
|
|
|
repository is present. The null key is a key consisting of all null bytes and
|
|
|
|
its only purpose is to ease the upgrade process from Mitaka to Newton. It is
|
|
|
|
highly recommended that the null key isn't used. It is no more secure than
|
|
|
|
storing credentials in plain text. If the null key is used, you should migrate
|
|
|
|
to a proper key repository using ``keystone-manage credential_setup`` and
|
|
|
|
``keystone-manage credential_migrate``.
|
2016-08-12 03:22:56 +00:00
|
|
|
|
|
|
|
Encryption key management
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
Key management of ``[credential] key_repository`` is handled with three
|
|
|
|
``keystone-manage`` commands:
|
|
|
|
|
|
|
|
1. ``keystone-manage credential_setup``
|
|
|
|
2. ``keystone-manage credential_rotate``
|
|
|
|
3. ``keystone-manage credential_migrate``
|
|
|
|
|
|
|
|
``keystone-manage credential_setup`` will populate ``[credential]
|
|
|
|
key_repository`` with new encryption keys. This must be done in order for
|
2016-09-07 16:15:03 +00:00
|
|
|
proper credential encryption to work, with the exception of the null key. This
|
|
|
|
step should only be done once.
|
2016-08-12 03:22:56 +00:00
|
|
|
|
|
|
|
``keystone-manage credential_rotate`` will create and rotate a new encryption
|
|
|
|
key in the ``[credential] key_repository``. This will only be done if all
|
|
|
|
credential key hashes match the hash of the current primary key. If any
|
|
|
|
credential has been encrypted with an older key, or secondary key, the rotation
|
|
|
|
will fail. Failing the rotation is necessary to prevent overrotation, which
|
|
|
|
would leave some credentials indecipherable since the key used to encrypt it
|
|
|
|
no longer exists. If this step fails, it is possible to forcibly re-key all
|
|
|
|
credentials using the same primary key with ``keystone-manage
|
|
|
|
credential_migrate``.
|
|
|
|
|
|
|
|
``keystone-manage credential_migrate`` will check the backend for credentials
|
|
|
|
whose key hash doesn't match the hash of the current primary key. Any
|
|
|
|
credentials with a key hash mismatching the current primary key will be
|
|
|
|
re-encrypted with the current primary key. The new cipher text and key hash
|
|
|
|
will be updated in the backend.
|