openstack/keystone
Code Issues Proposed changes

Update configuration.rst documentation

Browse Source 
* landing page: increase toc depth for configuration for easier navigation
* landing page: move keystone-manage man page to bottom

* created common keystone-manage commands doc, so config and man page can
  reference

* moved the sample config files section up near config file section
* moved fernet token section up near token section
* moved token flush near token section
* moved endpoint policy and endpoint filter near catalog

* removed references to devstack files that do not exist
* removed references to experimental and stable status for stable features
* removed references to keystoneclient CLI

* removed IANA portions, not config related
* removed section about user CRUD on v2.0 API, not config related

* lots of minor cleanup with syntax and wording

Change-Id: Id814b70d626299ba0717d6759ec6be5e97645a39
This commit is contained in:
Steve Martinelli 2016-11-18 13:46:23 -05:00
parent b6871c16a6
commit 2edc392567
4 changed files with 228 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

520
doc/source/configuration.rst
View File

@ -18,35 +18,14 @@
Configuring Keystone Configuring Keystone
==================== ====================
.. toctree:: Config Files
:maxdepth: 1 ============
man/keystone-manage Once keystone is installed, keystone is configured via a primary configuration
file (``etc/keystone.conf``), a PasteDeploy configuration file
Once keystone is installed, it is configured via a primary configuration file
(``etc/keystone.conf``), a PasteDeploy configuration file
(``etc/keystone-paste.ini``), possibly a separate logging configuration file, (``etc/keystone-paste.ini``), possibly a separate logging configuration file,
and initializing data into keystone using the command line client. and initializing data into keystone using the command line client.
By default, keystone starts a service on `IANA-assigned port 35357
<http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt>`_.
This may overlap with your system's ephemeral port range, so another process
may already be using this port without being explicitly configured to do so. To
prevent this scenario from occurring, it's recommended that you explicitly
exclude port 35357 from the available ephemeral port range. On a Linux system,
this would be accomplished by:
.. code-block:: bash
$ sysctl -w 'net.ipv4.ip_local_reserved_ports=35357'
To make the above change persistent,
``net.ipv4.ip_local_reserved_ports = 35357`` should be added to
``/etc/sysctl.conf`` or to ``/etc/sysctl.d/keystone.conf``.
Configuration Files
===================
The keystone configuration files are an ``ini`` file format based on Paste_, a The keystone configuration files are an ``ini`` file format based on Paste_, a
common system used to configure Python WSGI based applications. The PasteDeploy common system used to configure Python WSGI based applications. The PasteDeploy
configuration entries (WSGI pipeline definitions) can be provided in a separate configuration entries (WSGI pipeline definitions) can be provided in a separate
@ -62,6 +41,21 @@ parameters are in the primary configuration file ``keystone.conf``.
configuration file, i.e. configuration in ``keystone-paste.ini`` configuration file, i.e. configuration in ``keystone-paste.ini``
is not supported. is not supported.
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
--------------------------
The primary configuration file is organized into the following sections: The primary configuration file is organized into the following sections:
* ``[DEFAULT]`` - General configuration * ``[DEFAULT]`` - General configuration
@ -113,7 +107,7 @@ above. If not specified, WSGI pipeline definitions are loaded from the primary
configuration file. configuration file.
Identity sources Identity sources
---------------- ================
One of the most impactful decisions you'll have to make when configuring 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 is deciding how you want keystone to source your identity data.
@ -158,19 +152,14 @@ Keystone also supports the ability to store the domain-specific configuration
options in the keystone SQL database, managed via the Identity API, as opposed options in the keystone SQL database, managed via the Identity API, as opposed
to using domain-specific configuration files. to using domain-specific configuration files.
.. NOTE:: Support status for configuring options via the Identity API
*Experimental* (Kilo, Liberty, Mitaka)
*Stable* (Newton)
This capability (which is disabled by default) is enabled by specifying the This capability (which is disabled by default) is enabled by specifying the
following options in the main keystone configuration file: following options in the main keystone configuration file:
.. code-block:: ini .. code-block:: ini
[identity] [identity]
domain_specific_drivers_enabled = true domain_specific_drivers_enabled = true
domain_configurations_from_database = true domain_configurations_from_database = true
Once enabled, any existing domain-specific configuration files in the Once enabled, any existing domain-specific configuration files in the
configuration directory will be ignored and only those domain-specific configuration directory will be ignored and only those domain-specific
@ -337,7 +326,7 @@ following property:
immutable for a given installation. immutable for a given installation.
Authentication Plugins Authentication Plugins
---------------------- ======================
.. NOTE:: .. NOTE::
@ -359,7 +348,7 @@ container web server that sets the ``REMOTE_USER`` environment variable. For
more details, refer to :doc:`External Authentication <external-auth>`. more details, refer to :doc:`External Authentication <external-auth>`.
How to Implement an Authentication Plugin How to Implement an Authentication Plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------------------
All authentication plugins must extend the All authentication plugins must extend the
:class:`keystone.auth.plugins.base.AuthMethodHandler` class and implement the :class:`keystone.auth.plugins.base.AuthMethodHandler` class and implement the
@ -407,6 +396,8 @@ plugins specified in ``methods``. This effectively disables external
authentication. For more details, refer to :doc:`ExternalAuthentication authentication. For more details, refer to :doc:`ExternalAuthentication
<external-auth>`. <external-auth>`.
Token Drivers and Providers
===========================
Token Persistence Driver Token Persistence Driver
------------------------ ------------------------
@ -429,20 +420,24 @@ Token Provider
-------------- --------------
Keystone supports customizable token providers and it is specified in the Keystone supports customizable token providers and it is specified in the
``[token]`` section of the configuration file. Keystone provides a UUID and ``[token]`` section of the configuration file. Keystone provides two token
Fernet token provider. However, users may register their own token provider options (``fernet`` and ``uuid``, with ``fernet`` being the default).
provider by configuring the following property. Users may register their own token provider by configuring the
``[token] provider`` property.
* ``provider`` - token provider driver. Defaults to ``fernet``. Implemented by * ``fernet`` - A Fernet based token provider. Implemented by
:class:`keystone.token.providers.fernet.Provider` :class:`keystone.token.providers.fernet.Provider`
* ``uuid`` - A UUID based token provider. Implemented by
:class:`keystone.token.providers.uuid.Provider`
UUID or Fernet? UUID or Fernet?
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Each token format uses different technologies to achieve various performance, Each token format uses different technologies to achieve various performance,
scaling and architectural requirements. scaling and architectural requirements.
UUID tokens contain randomly generated UUID4 payloads that are issued and UUID tokens contain randomly generated UUID4 IDs that are issued and
validated by the identity service. They are encoded using their hex digest for validated by the identity service. They are encoded using their hex digest for
transport and are thus URL-friendly. They must be persisted by the identity transport and are thus URL-friendly. They must be persisted by the identity
service in order to be later validated. Revoking them is simply a matter of service in order to be later validated. Revoking them is simply a matter of
@ -463,8 +458,56 @@ using ``keystone-manage fernet_rotate``.
.. support_matrix:: token-support-matrix.ini .. support_matrix:: token-support-matrix.ini
Encryption Keys for Fernet Tokens
=================================
``keystone-manage fernet_setup`` will attempt to create a key repository as
configured in the ``[fernet_tokens]`` section of ``keystone.conf`` and
bootstrap it with encryption keys.
A single 256-bit key is actually composed of two smaller keys: a 128-bit key
used for SHA256 HMAC signing and a 128-bit key used for AES encryption. See the
`Fernet token <https://github.com/fernet/spec>`_ specification for more detail.
``keystone-manage fernet_rotate`` will rotate encryption keys through the
following states:
* **Staged key**: In a key rotation, a new key is introduced into the rotation
in this state. Only one key is considered to be the *staged* key at any given
time. This key will become the *primary* during the *next* key rotation. This
key is only used to validate tokens and serves to avoid race conditions in
multi-node deployments (all nodes should recognize all *primary* keys in the
deployment at all times). In a multi-node keystone deployment this would
allow for the *staged* key to be replicated to all keystone nodes before
being promoted to *primary* on a single node. This prevents the case where a
*primary* key is created on one keystone node and tokens encrypted/signed with
that new *primary* are rejected on another keystone node because the new
*primary* doesn't exist there yet.
* **Primary key**: In a key rotation, the old *staged* key is promoted to be
the *primary*. Only one key is considered to be the *primary* key at any
given time. This is the key used to generate new tokens. This key is also
used to validate previously generated tokens.
* **Secondary keys**: In a key rotation, the old *primary* key is demoted to be
a *secondary* key. *Secondary* keys are only used to validate previously
generated tokens. You can maintain any number of *secondary* keys, up to
``[fernet_tokens] max_active_keys`` (where "active" refers to the sum of all
recognized keys in any state: *staged*, *primary* or *secondary*). When
``max_active_keys`` is exceeded during a key rotation, the oldest keys are
discarded.
When a new primary key is created, all new tokens will be encrypted using the
new primary key. The old primary key is demoted to a secondary key, which can
still be used for validating tokens. Excess secondary keys (beyond
``[fernet_tokens] max_active_keys``) are revoked. Revoked keys are permanently
deleted.
Rotating keys too frequently, or with ``[fernet_tokens] max_active_keys`` set
too low, will cause tokens to become invalid prior to their expiration.
Caching Layer Caching Layer
------------- =============
Keystone's configuration file offers two separate sections related to caching, Keystone's configuration file offers two separate sections related to caching,
``[memcache]`` and ``[cache]``. The ``[memcache]`` section provides caching ``[memcache]`` and ``[cache]``. The ``[memcache]`` section provides caching
@ -488,8 +531,8 @@ cached usually has a ``caching`` boolean value that will toggle caching for
that specific section. The current default behavior is that global and that specific section. The current default behavior is that global and
subsystem caching is enabled. subsystem caching is enabled.
``[cache]`` configuration section: ``[cache]`` configuration section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------------------------------
* ``enabled`` - enables/disables caching across all of keystone * ``enabled`` - enables/disables caching across all of keystone
* ``debug_cache_backend`` - enables more in-depth logging from the cache * ``debug_cache_backend`` - enables more in-depth logging from the cache
@ -612,7 +655,7 @@ For more information about the different backends (and configuration options):
Certificates for PKI Certificates for PKI
-------------------- ====================
PKI stands for Public Key Infrastructure. Tokens are documents, PKI stands for Public Key Infrastructure. Tokens are documents,
cryptographically signed using the X509 standard. In order to work correctly cryptographically signed using the X509 standard. In order to work correctly
@ -634,7 +677,7 @@ that will run keystone. The values that specify the certificates are under the
above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem`` above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem``
Signing Certificate Issued by External CA Signing Certificate Issued by External CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------------------
You may use a signing certificate issued by an external CA instead of generated You may use a signing certificate issued by an external CA instead of generated
by ``keystone-manage``. However, certificate issued by external CA must satisfy by ``keystone-manage``. However, certificate issued by external CA must satisfy
@ -652,7 +695,7 @@ involves:
Request Signing Certificate from External CA Request Signing Certificate from External CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------------------
One way to request a signing certificate from an external CA is to first 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. generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI.
@ -696,7 +739,7 @@ format.
Install External Signing Certificate Install External Signing Certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ------------------------------------
Assuming you have the following already: Assuming you have the following already:
@ -721,8 +764,8 @@ If your certificate directory path is different from the default
section of the configuration file. section of the configuration file.
Generating a Signing Certificate using pki_setup Generating a Signing Certificate using ``pki_setup``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------------------------
``keystone-manage pki_setup`` is a development tool. We recommend that you do ``keystone-manage pki_setup`` is a development tool. We recommend that you do
not use ``keystone-manage pki_setup`` in a production environment. In not use ``keystone-manage pki_setup`` in a production environment. In
@ -744,61 +787,13 @@ If ``keystone-manage pki_setup`` is not used then these options don't need to
be set. be set.
Encryption Keys for Fernet
--------------------------
``keystone-manage fernet_setup`` will attempt to create a key repository as
configured in the ``[fernet_tokens]`` section of ``keystone.conf`` and
bootstrap it with encryption keys.
A single 256-bit key is actually composed of two smaller keys: a 128-bit key
used for SHA256 HMAC signing and a 128-bit key used for AES encryption. See the
`Fernet token <https://github.com/fernet/spec>`_ specification for more detail.
``keystone-manage fernet_rotate`` will rotate encryption keys through the
following states:
* **Staged key**: In a key rotation, a new key is introduced into the rotation
in this state. Only one key is considered to be the *staged* key at any given
time. This key will become the *primary* during the *next* key rotation. This
key is only used to validate tokens and serves to avoid race conditions in
multi-node deployments (all nodes should recognize all *primary* keys in the
deployment at all times). In a multi-node keystone deployment this would
allow for the *staged* key to be replicated to all keystone nodes before
being promoted to *primary* on a single node. This prevents the case where a
*primary* key is created on one keystone node and tokens encrypted/signed with
that new *primary* are rejected on another keystone node because the new
*primary* doesn't exist there yet.
* **Primary key**: In a key rotation, the old *staged* key is promoted to be
the *primary*. Only one key is considered to be the *primary* key at any
given time. This is the key used to generate new tokens. This key is also
used to validate previously generated tokens.
* **Secondary keys**: In a key rotation, the old *primary* key is demoted to be
a *secondary* key. *Secondary* keys are only used to validate previously
generated tokens. You can maintain any number of *secondary* keys, up to
``[fernet_tokens] max_active_keys`` (where "active" refers to the sum of all
recognized keys in any state: *staged*, *primary* or *secondary*). When
``max_active_keys`` is exceeded during a key rotation, the oldest keys are
discarded.
When a new primary key is created, all new tokens will be encrypted using the
new primary key. The old primary key is demoted to a secondary key, which can
still be used for validating tokens. Excess secondary keys (beyond
``[fernet_tokens] max_active_keys``) are revoked. Revoked keys are permanently
deleted.
Rotating keys too frequently, or with ``[fernet_tokens] max_active_keys`` set
too low, will cause tokens to become invalid prior to their expiration.
Service Catalog Service Catalog
--------------- ===============
Keystone provides two configuration options for your service catalog. Keystone provides two configuration options for managing a service catalog.
SQL-based Service Catalog (``sql.Catalog``) SQL-based Service Catalog (``sql.Catalog``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -------------------------------------------
A dynamic database-backed driver fully supporting persistent configuration. A dynamic database-backed driver fully supporting persistent configuration.
@ -811,21 +806,18 @@ A dynamic database-backed driver fully supporting persistent configuration.
.. NOTE:: .. NOTE::
A `template_file` does not need to be defined for the sql.Catalog driver. A `template_file` does not need to be defined for the sql based catalog.
To build your service catalog using this driver, see the built-in help: To build your service catalog using this driver, see the built-in help:
.. code-block:: bash .. code-block:: bash
$ openstack --help $ openstack --help
$ openstack help service create $ openstack service create --help
$ openstack help endpoint create $ openstack endpoint create --help
You can also refer to `an example in keystone (tools/sample_data.sh)
<https://git.openstack.org/cgit/openstack/keystone/tree/tools/sample_data.sh>`_.
File-based Service Catalog (``templated.Catalog``) File-based Service Catalog (``templated.Catalog``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------------------------
The templated catalog is an in-memory backend initialized from a read-only The templated catalog is an in-memory backend initialized from a read-only
``template_file``. Choose this option only if you know that your service ``template_file``. Choose this option only if you know that your service
@ -850,9 +842,8 @@ The value of ``template_file`` is expected to be an absolute path to your
service catalog configuration. An example ``template_file`` is included in service catalog configuration. An example ``template_file`` is included in
keystone, however you should create your own to reflect your deployment. keystone, however you should create your own to reflect your deployment.
Another such example is `available in devstack Endpoint Filtering
(files/default_catalog.templates) ==================
<https://git.openstack.org/cgit/openstack-dev/devstack/tree/files/default_catalog.templates>`_.
Endpoint Filtering enables creation of ad-hoc catalogs for each project-scoped Endpoint Filtering enables creation of ad-hoc catalogs for each project-scoped
token request. token request.
@ -877,67 +868,8 @@ For example:
See `API Specification for Endpoint Filtering <http://developer.openstack.org/ See `API Specification for Endpoint Filtering <http://developer.openstack.org/
api-ref/identity/v3-ext/#os-ep-filter-api>`_ for the details of API definition. api-ref/identity/v3-ext/#os-ep-filter-api>`_ for the details of API definition.
.. NOTE:: Support status for Endpoint Filtering
*Experimental* (Icehouse, Juno)
*Stable* (Kilo)
Logging
-------
Logging is configured externally to the rest of keystone. Configure the path to
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.
A sample ``log_config_append`` file is included with the project at
``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
`Python logging module`_, which includes extensive configuration options for
choosing the output levels and formats.
.. _Paste: http://pythonpaste.org/
.. _`Python logging module`: http://docs.python.org/library/logging.html
SSL
---
A secure deployment should have keystone running in a web server (such as
Apache httpd), or behind an SSL terminator.
User CRUD additions for the V2.0 API
------------------------------------
For the V2.0 API, keystone provides an additional capability that allows users
to use a HTTP PATCH to change their own password.
Each user can then change their own password with a HTTP PATCH :
.. code-block:: bash
$ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<userid> -H "Content-type: application/json" \
-H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}'
In addition to changing their password all of the user's current tokens will be
revoked.
Inherited Role Assignments
--------------------------
Keystone provides an optional capability to assign roles on a project or domain
that, rather than affect the project or domain itself, are instead inherited to
the project subtree or to all projects owned by that domain. This capability is
enabled by default, but can be disabled by including the following in
``keystone.conf``:
.. code-block:: ini
[os_inherit]
enabled = False
Endpoint Policy Endpoint Policy
--------------- ===============
The Endpoint Policy feature provides associations between service endpoints The Endpoint Policy feature provides associations between service endpoints
and policies that are already stored in the Identity server and referenced and policies that are already stored in the Identity server and referenced
@ -955,14 +887,46 @@ See `API Specification for Endpoint Policy <http://specs.openstack.org/
openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`_ openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`_
for the details of API definition. for the details of API definition.
.. NOTE:: Support status for Endpoint Policy Logging
=======
*Experimental* (Juno) Logging is configured externally to the rest of keystone. Configure the path to
*Stable* (Kilo) 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.
A sample ``log_config_append`` file is included with the project at
``etc/logging.conf.sample``. Like other OpenStack projects, keystone uses the
`Python logging module`_, which includes extensive configuration options for
choosing the output levels and formats.
.. _Paste: http://pythonpaste.org/
.. _`Python logging module`: http://docs.python.org/library/logging.html
SSL
===
A secure deployment should have keystone running in a web server (such as
Apache httpd), or behind an SSL terminator.
Inherited Role Assignments
==========================
Keystone provides an optional capability to assign roles on a project or domain
that, rather than affect the project or domain itself, are instead inherited to
the project subtree or to all projects owned by that domain. This capability is
enabled by default, but can be disabled by including the following in
``keystone.conf``:
.. code-block:: ini
[os_inherit]
enabled = False
OAuth1 1.0a OAuth1 1.0a
----------- ===========
The OAuth 1.0a feature provides the ability for Identity users to delegate The OAuth 1.0a feature provides the ability for Identity users to delegate
roles to third party consumers via the OAuth 1.0a specification. roles to third party consumers via the OAuth 1.0a specification.
@ -998,14 +962,9 @@ See `API Specification for OAuth 1.0a <http://specs.openstack.org/openstack/
keystone-specs/api/v3/identity-api-v3-os-oauth1-ext.html>`_ for the details of keystone-specs/api/v3/identity-api-v3-os-oauth1-ext.html>`_ for the details of
API definition. API definition.
.. NOTE:: Support status for OAuth 1.0a
*Experimental* (Havana, Icehouse)
*Stable* (Juno)
Revocation Events Revocation Events
----------------- =================
The Revocation Events feature provides a list of token revocations. Each event 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 expresses a set of criteria which describes a set of tokens that are
@ -1023,14 +982,9 @@ See `API Specification for Revocation Events <https://specs.openstack.org/
openstack/keystone-specs/api/v3/identity-api-v3-os-revoke-ext.html>`_ for openstack/keystone-specs/api/v3/identity-api-v3-os-revoke-ext.html>`_ for
the details of API definition. the details of API definition.
.. NOTE:: Support status for Revocation Events
*Experimental* (Juno)
*Stable* (Kilo)
Token Binding Token Binding
------------- =============
Token binding refers to the practice of embedding information from external Token binding refers to the practice of embedding information from external
authentication providers (like a company's Kerberos server) inside the token authentication providers (like a company's Kerberos server) inside the token
@ -1062,16 +1016,16 @@ should be set to one of the following modes:
* named enable bind checking and require that the specified authentication * named enable bind checking and require that the specified authentication
mechanism is used. e.g.: mechanism is used. e.g.:
.. code-block:: ini .. code-block:: ini
[token] [token]
enforce_token_bind = kerberos enforce_token_bind = kerberos
*Do not* set ``enforce_token_bind = named`` as there is not an authentication *Do not* set ``enforce_token_bind = named`` as there is not an authentication
mechanism called ``named``. mechanism called ``named``.
Limiting the number of entities returned in a collection Limiting list return size
-------------------------------------------------------- =========================
Keystone provides a method of setting a limit to the number of entities Keystone provides a method of setting a limit to the number of entities
returned in a collection, which is useful to prevent overly long response times returned in a collection, which is useful to prevent overly long response times
@ -1091,7 +1045,7 @@ collection will be set to ``true``.
URL safe naming of projects and domains URL safe naming of projects and domains
--------------------------------------- =======================================
In the future, keystone may offer the ability to identify a project in a In the future, keystone may offer the ability to identify a project in a
hierarchy via a URL style of naming from the root of the hierarchy (for example hierarchy via a URL style of naming from the root of the hierarchy (for example
@ -1122,8 +1076,8 @@ status code of 401 (Unauthorized).
It is recommended that installations take the steps necessary to where they 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. can run with both options set to ``strict`` as soon as is practical.
Configuring the Health Check Health Check middleware
---------------------------- =======================
This health check middleware allows an operator to configure the endpoint URL 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 that will provide information to a load balancer if the given API endpoint at
@ -1151,22 +1105,10 @@ most efficient checks.
For more information and configuration options for the middleware see For more information and configuration options for the middleware see
`oslo.middleware <http://docs.openstack.org/developer/oslo.middleware/api.html#oslo_middleware.Healthcheck>`_. `oslo.middleware <http://docs.openstack.org/developer/oslo.middleware/api.html#oslo_middleware.Healthcheck>`_.
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``
.. _`API protection with RBAC`: .. _`API protection with RBAC`:
Keystone API protection with Role Based Access Control (RBAC) API protection with Role Based Access Control (RBAC)
============================================================= =====================================================
Like most OpenStack projects, keystone supports the protection of its APIs by Like most OpenStack projects, keystone supports the protection of its APIs by
defining policy rules based on an RBAC approach. These are stored in a JSON defining policy rules based on an RBAC approach. These are stored in a JSON
@ -1338,100 +1280,47 @@ return an empty list from your new database):
values, or deployed keystone to a different endpoint, you will need to values, or deployed keystone to a different endpoint, you will need to
change the provided command accordingly. change the provided command accordingly.
Initializing Keystone ``keystone-manage``
===================== ===================
``keystone-manage`` is designed to execute commands that cannot be administered ``keystone-manage`` is the command line tool which interacts with the Keystone
through the normal REST API. At the moment, the following calls are supported: 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.
* ``bootstrap``: Perform the basic bootstrap process. .. include:: man/commands.rst
* ``credential_migrate``: Encrypt credentials using a new primary key.
* ``credential_rotate``: Rotate Fernet keys for credential encryption.
* ``credential_setup``: Setup a Fernet key repository for credential encryption.
* ``db_sync``: Sync the database.
* ``db_version``: Print the current migration version of the database.
* ``doctor``: Diagnose common problems with keystone deployments.
* ``domain_config_upload``: Upload domain configuration file.
* ``fernet_rotate``: Rotate keys in the Fernet key repository.
* ``fernet_setup``: Setup a Fernet key repository.
* ``mapping_engine``: Test your federation mapping rules.
* ``mapping_populate``: Prepare domain-specific LDAP backend
* ``mapping_purge``: Purge the identity mapping table.
* ``pki_setup``: Initialize the certificates used to sign revocation lists.
* ``saml_idp_metadata``: Generate identity provider metadata.
* ``token_flush``: Purge expired tokens
Invoking ``keystone-manage`` by itself will give you additional usage Removing Expired Tokens
information. =======================
The private key used for token signing can only be read by its owner. This In the SQL backend expired UUID tokens are not automatically removed. These
prevents unauthorized users from spuriously signing tokens. tokens can be removed with:
``keystone-manage pki_setup`` Should be run as the same system user that will
be running the keystone service to ensure proper ownership for the private key
file and the associated certificates.
Adding Users, Projects, and Roles via Command Line Interfaces .. code-block:: bash
=============================================================
Keystone APIs are protected by the rules in the policy file. The default policy $ keystone-manage token_flush
rules require admin credentials to administer ``users``, ``projects``, and
``roles``. See section
`Keystone API protection with Role Based Access Control (RBAC)`_ for more
details on policy files.
The keystone command line interface packaged in `python-keystoneclient`_ only It is recommended to run this command periodically with ``cron`` if using UUID
supports the Identity v2.0 API. The OpenStack common command line interface tokens.
packaged in `python-openstackclient`_ supports both v2.0 and v3 APIs.
With both command line interfaces there are two ways to configure the client to
use admin credentials, using either an existing token or password credentials.
.. NOTE:: .. NOTE::
As of the Juno release, it is recommended to use It it not required to run this command at all if using Fernet tokens. Fernet
``python-openstackclient``, as it supports both v2.0 and v3 APIs. For the tokens are not persisted.
purpose of backwards compatibility, the CLI packaged in
``python-keystoneclient`` is not being removed. Supported clients
=================
There are two supported clients, `python-keystoneclient`_ project provides
python bindings and `python-openstackclient`_ provides a command line
interface.
.. _`python-openstackclient`: http://docs.openstack.org/developer/python-openstackclient/ .. _`python-openstackclient`: http://docs.openstack.org/developer/python-openstackclient/
.. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/ .. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/
Authenticating with a Token
---------------------------
.. NOTE:: Authenticating with a Password via CLI
--------------------------------------
If your keystone deployment is brand new, you will need to use this
authentication method, along with your ``[DEFAULT] admin_token``.
To authenticate with keystone using a token and ``python-openstackclient``, set
the following flags.
* ``--os-url OS_URL``: Keystone endpoint the user communicates with
* ``--os-token OS_TOKEN``: User's service token
To administer a keystone endpoint, your token should be either belong to a user
with the ``admin`` role, or, if you haven't created one yet, should be equal to
the value defined by ``[DEFAULT] admin_token`` in your ``keystone.conf``.
You can also set these variables in your environment so that they do not need
to be passed as arguments each time:
.. code-block:: bash
$ export OS_URL=http://localhost:35357/v2.0
$ export OS_TOKEN=ADMIN
Instead of ``python-openstackclient``, if using ``python-keystoneclient``, set
the following:
* ``--os-endpoint OS_SERVICE_ENDPOINT``: equivalent to ``--os-url OS_URL``
* ``--os-service-token OS_SERVICE_TOKEN``: equivalent to
``--os-token OS_TOKEN``
Authenticating with a Password
------------------------------
To authenticate with keystone using a password and ``python-openstackclient``, To authenticate with keystone using a password and ``python-openstackclient``,
set the following flags, note that the following user referenced below should set the following flags, note that the following user referenced below should
@ -1452,36 +1341,11 @@ to be passed as arguments each time:
$ export OS_PROJECT_NAME=my_project $ export OS_PROJECT_NAME=my_project
$ export OS_AUTH_URL=http://localhost:35357/v2.0 $ export OS_AUTH_URL=http://localhost:35357/v2.0
If using ``python-keystoneclient``, set the following instead: For example, the commands ``user list``, ``token issue`` and ``project create``
can be invoked as follows:
* ``--os-tenant-name OS_TENANT_NAME``: equivalent to
``--os-project-name OS_PROJECT_NAME``
Example usage
-------------
``python-openstackclient`` is set up to expect commands in the general form of:
.. code-block:: bash .. code-block:: bash
$ openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]
For example, the commands ``user list`` and ``project create`` can be invoked
as follows:
.. code-block:: bash
# Using token authentication, with environment variables
$ export OS_URL=http://127.0.0.1:35357/v2.0/
$ export OS_TOKEN=secrete_token
$ openstack user list
$ openstack project create demo
# Using token authentication, with flags
$ openstack --os-token=secrete --os-url=http://127.0.0.1:35357/v2.0/ user list
$ openstack --os-token=secrete --os-url=http://127.0.0.1:35357/v2.0/ project create demo
# Using password authentication, with environment variables # Using password authentication, with environment variables
$ export OS_USERNAME=admin $ export OS_USERNAME=admin
$ export OS_PASSWORD=secrete $ export OS_PASSWORD=secrete
@ -1489,27 +1353,15 @@ as follows:
$ export OS_AUTH_URL=http://localhost:35357/v2.0 $ export OS_AUTH_URL=http://localhost:35357/v2.0
$ openstack user list $ openstack user list
$ openstack project create demo $ openstack project create demo
$ openstack token issue
# Using password authentication, with flags # Using password authentication, with flags
$ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 user list $ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 user list
$ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 project create demo $ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 project create demo
Removing Expired Tokens
=======================
In the SQL backend expired tokens are not automatically removed. These tokens Using an LDAP server
can be removed with: ====================
.. code-block:: bash
$ keystone-manage token_flush
The memcache backend automatically discards expired tokens and so flushing is
unnecessary and if attempted will fail with a NotImplemented error.
Configuring the LDAP Identity Provider
======================================
As an alternative to the SQL Database backing store, keystone can use a As an alternative to the SQL Database backing store, keystone can use a
directory server to provide the Identity service. An example schema for directory server to provide the Identity service. An example schema for
@ -1696,10 +1548,10 @@ the standard options permitted by the ``TLS_REQCERT`` TLS option.
.. NOTE:: .. NOTE::
If unable to connect to LDAP via keystone (more specifically, if a 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`` *SERVER DOWN* error is seen), set the ``TLS_CACERT`` in
to the same value specified in the ``[ldap] tls_certificate`` section of ``/etc/ldap/ldap.conf`` to the same value specified in the
``keystone.conf``. ``[ldap] tls_certificate`` section of ``keystone.conf``.
Read Only LDAP Read Only LDAP
-------------- --------------

27
doc/source/index.rst
View File

@ -50,7 +50,6 @@ Getting Started
:maxdepth: 1 :maxdepth: 1
installing installing
configuration
upgrading upgrading
performance performance
apache-httpd apache-httpd
@ -60,6 +59,14 @@ Getting Started
key_terms key_terms
community community
Configuration
=============
.. toctree::
:maxdepth: 2
configuration
Advanced Topics Advanced Topics
=============== ===============
@ -67,7 +74,6 @@ Advanced Topics
:maxdepth: 2 :maxdepth: 2
federation/federated_identity federation/federated_identity
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
@ -77,14 +83,6 @@ Advanced Topics
external-auth external-auth
security_compliance security_compliance
Man Pages
=========
.. toctree::
:maxdepth: 1
man/keystone-manage
Developers Documentation Developers Documentation
======================== ========================
.. toctree:: .. toctree::
@ -101,7 +99,6 @@ Developers Documentation
services services
online_schema_migration_examples online_schema_migration_examples
Sample Configuration File Sample Configuration File
========================= =========================
@ -110,6 +107,14 @@ Sample Configuration File
sample_config sample_config
Man Pages
=========
.. toctree::
:maxdepth: 1
man/keystone-manage
Code Documentation Code Documentation
================== ==================
.. toctree:: .. toctree::

25
doc/source/man/commands.rst Normal file
View File

@ -0,0 +1,25 @@
General keystone-manage options:
--------------------------------
* ``--help`` : display verbose help output.
Invoking ``keystone-manage`` by itself will give you some usage information.
Available commands:
* ``bootstrap``: Perform the basic bootstrap process.
* ``credential_migrate``: Encrypt credentials using a new primary key.
* ``credential_rotate``: Rotate Fernet keys for credential encryption.
* ``credential_setup``: Setup a Fernet key repository for credential encryption.
* ``db_sync``: Sync the database.
* ``db_version``: Print the current migration version of the database.
* ``doctor``: Diagnose common problems with keystone deployments.
* ``domain_config_upload``: Upload domain configuration file.
* ``fernet_rotate``: Rotate keys in the Fernet key repository.
* ``fernet_setup``: Setup a Fernet key repository for token encryption.
* ``mapping_populate``: Prepare domain-specific LDAP backend.
* ``mapping_purge``: Purge the identity mapping table.
* ``mapping_engine``: Test your federation mapping rules.
* ``pki_setup``: Initialize the certificates used to sign revocation lists. **deprecated**
* ``saml_idp_metadata``: Generate identity provider metadata.
* ``token_flush``: Purge expired tokens.

26
doc/source/man/keystone-manage.rst
View File

@ -31,31 +31,7 @@ USAGE
``keystone-manage [options] action [additional args]`` ``keystone-manage [options] action [additional args]``
General keystone-manage options: .. include:: commands.rst
--------------------------------
* ``--help`` : display verbose help output.
Invoking ``keystone-manage`` by itself will give you some usage information.
Available commands:
* ``bootstrap``: Perform the basic bootstrap process.
* ``credential_migrate``: Encrypt credentials using a new primary key.
* ``credential_rotate``: Rotate Fernet keys for credential encryption.
* ``credential_setup``: Setup a Fernet key repository for credential encryption.
* ``db_sync``: Sync the database.
* ``db_version``: Print the current migration version of the database.
* ``doctor``: Diagnose common problems with keystone deployments.
* ``domain_config_upload``: Upload domain configuration file.
* ``fernet_rotate``: Rotate keys in the Fernet key repository.
* ``fernet_setup``: Setup a Fernet key repository for token encryption.
* ``mapping_populate``: Prepare domain-specific LDAP backend.
* ``mapping_purge``: Purge the identity mapping table.
* ``mapping_engine``: Test your federation mapping rules.
* ``pki_setup``: Initialize the certificates used to sign revocation lists. **deprecated**
* ``saml_idp_metadata``: Generate identity provider metadata.
* ``token_flush``: Purge expired tokens.
OPTIONS OPTIONS
======= =======