summaryrefslogtreecommitdiffstats
path: root/keystone-moon/doc/source/configuration.rst
diff options
context:
space:
mode:
Diffstat (limited to 'keystone-moon/doc/source/configuration.rst')
-rw-r--r--keystone-moon/doc/source/configuration.rst331
1 files changed, 224 insertions, 107 deletions
diff --git a/keystone-moon/doc/source/configuration.rst b/keystone-moon/doc/source/configuration.rst
index 574b26be..e78c0ac6 100644
--- a/keystone-moon/doc/source/configuration.rst
+++ b/keystone-moon/doc/source/configuration.rst
@@ -52,8 +52,8 @@ Starting and Stopping Keystone under Eventlet
Running keystone under eventlet has been deprecated as of the Kilo release.
Support for utilizing eventlet will be removed as of the M-release. The
- recommended deployment is to run keystone in a WSGI server
- (e.g. ``mod_wsgi`` under ``HTTPD``).
+ recommended deployment is to run keystone in a WSGI server such as Apache
+ httpd with ``mod_wsgi``.
Keystone can be run using either its built-in eventlet server or it can be run
embedded in a web server. While the eventlet server is convenient and easy to
@@ -73,7 +73,7 @@ services are configured to run in a single process.
.. NOTE::
- The separation into ``admin`` and ``main`` interfaces is an historical
+ The separation into ``admin`` and ``main`` interfaces is a historical
anomaly. The new V3 API provides the same interface on both the admin and
main interfaces (this can be configured in ``keystone-paste.ini``, but the
default is to have both the same). The V2.0 API provides a limited public
@@ -113,8 +113,8 @@ The primary configuration file is organized into the following sections:
* ``[cache]`` - Caching layer configuration
* ``[catalog]`` - Service catalog driver configuration
* ``[credential]`` - Credential system driver configuration
-* ``[endpoint_filter]`` - Endpoint filtering extension configuration
-* ``[endpoint_policy]`` - Endpoint policy extension configuration
+* ``[endpoint_filter]`` - Endpoint filtering configuration
+* ``[endpoint_policy]`` - Endpoint policy configuration
* ``[eventlet_server]`` - Eventlet server configuration
* ``[eventlet_server_ssl]`` - Eventlet server SSL configuration
* ``[federation]`` - Federation driver configuration
@@ -124,7 +124,7 @@ The primary configuration file is organized into the following sections:
* ``[ldap]`` - LDAP configuration options
* ``[memcache]`` - Memcache configuration options
* ``[oauth1]`` - OAuth 1.0a system driver configuration
-* ``[os_inherit]`` - Inherited role assignment extension
+* ``[os_inherit]`` - Inherited role assignment configuration
* ``[paste_deploy]`` - Pointer to the PasteDeploy configuration file
* ``[policy]`` - Policy system driver configuration for RBAC
* ``[resource]`` - Resource system driver configuration
@@ -134,7 +134,7 @@ The primary configuration file is organized into the following sections:
* ``[signing]`` - Cryptographic signatures for PKI based tokens
* ``[ssl]`` - SSL certificate generation configuration
* ``[token]`` - Token driver & token provider configuration
-* ``[trust]`` - Trust extension configuration
+* ``[trust]`` - Trust configuration
The Keystone primary configuration file is expected to be named
``keystone.conf``. When starting Keystone, you can specify a different
@@ -423,7 +423,7 @@ Token Persistence Driver
Keystone supports customizable token persistence drivers. These can be
specified in the ``[token]`` section of the configuration file. Keystone
provides three non-test persistence backends. These can be set with the
-``[token]\driver`` configuration option.
+``[token] driver`` configuration option.
The drivers Keystone provides are:
@@ -438,7 +438,7 @@ The drivers Keystone provides are:
* ``memcache`` - The memcached based token persistence backend. This backend
relies on ``dogpile.cache`` and stores the token data in a set of memcached
- servers. The servers URLs are specified in the ``[memcache]\servers``
+ servers. The servers URLs are specified in the ``[memcache] servers``
configuration option in the Keystone config. Implemented by
:class:`keystone.token.persistence.backends.memcache.Token`
@@ -446,9 +446,10 @@ The drivers Keystone provides are:
.. WARNING::
It is recommended you use the ``memcache_pool`` backend instead of
``memcache`` as the token persistence driver if you are deploying Keystone
- under eventlet instead of Apache + mod_wsgi. This recommendation is due to
- known issues with the use of ``thread.local`` under eventlet that can allow
- the leaking of memcache client objects and consumption of extra sockets.
+ under eventlet instead of Apache httpd with ``mod_wsgi``. This
+ recommendation is due to known issues with the use of ``thread.local``
+ under eventlet that can allow the leaking of memcache client objects and
+ consumption of extra sockets.
Token Provider
@@ -539,7 +540,8 @@ disabled.
backend will need to be specified. Current functional backends are:
* ``dogpile.cache.memcached`` - Memcached backend using the standard
- `python-memcached`_ library
+ `python-memcached`_ library (recommended for use with Apache httpd with
+ ``mod_wsgi``)
* ``dogpile.cache.pylibmc`` - Memcached backend using the `pylibmc`_
library
* ``dogpile.cache.bmemcached`` - Memcached using `python-binary-memcached`_
@@ -548,7 +550,7 @@ disabled.
* ``dogpile.cache.dbm`` - local DBM file backend
* ``dogpile.cache.memory`` - in-memory cache
* ``keystone.cache.mongo`` - MongoDB as caching backend
- * ``keystone.cache.memcache_pool`` - An eventlet safe implementation of
+ * ``keystone.cache.memcache_pool`` - An eventlet-safe implementation of
``dogpile.cache.memcached``. This implementation also provides client
connection re-use.
@@ -651,7 +653,6 @@ For more information about the different backends (and configuration options):
.. _`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
-.. _`PyMongo API`: http://api.mongodb.org/python/current/api/pymongo/index.html
Certificates for PKI
@@ -897,17 +898,46 @@ Another such example is `available in devstack
(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
+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
+
+See `API Specification for Endpoint Filtering <http://specs.openstack.org/
+openstack/keystone-specs/api/v3/identity-api-v3-os-ep-filter-ext.html>`_ 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`` option of
-``keystone.conf``. If you wish to route all your logging through syslog, set
-the ``[DEFAULT] use_syslog`` option.
+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`` file is included with the project at
+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
+`Python logging module`_, which includes extensive configuration options for
choosing the output levels and formats.
.. _Paste: http://pythonpaste.org/
@@ -926,7 +956,7 @@ this section. Here is the description of each of them and their purpose:
The SSL configuration options available to the eventlet server
(``keystone-all``) described here are severely limited. A secure
deployment should have Keystone running in a web server (such as Apache
- HTTPd), or behind an SSL terminator. When running Keystone in a web server
+ httpd), or behind an SSL terminator. When running Keystone in a web server
or behind an SSL terminator the options described in this section have no
effect and SSL is configured in the web server or SSL terminator.
@@ -1005,28 +1035,11 @@ and is only recommended for developments environment. We do not recommend using
``ssl_setup`` for production environments.
-User CRUD extension for the V2.0 API
+User CRUD additions for the V2.0 API
------------------------------------
-.. NOTE::
-
- The core V3 API includes user operations so no extension needs to be
- enabled for the V3 API.
-
-For the V2.0 API, Keystone provides a user CRUD filter that can be added to the
-public_api pipeline. This user crud filter allows users to use a HTTP PATCH to
-change their own password. To enable this extension you should define a
-user_crud_extension filter, insert it after the ``*_body`` middleware and
-before the ``public_service`` app in the public_api WSGI pipeline in
-``keystone-paste.ini`` e.g.:
-
-.. code-block:: ini
-
- [filter:user_crud_extension]
- paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory
-
- [pipeline:public_api]
- pipeline = url_normalize token_auth admin_token_auth json_body debug ec2_extension user_crud_extension public_service
+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 :
@@ -1039,19 +1052,112 @@ In addition to changing their password all of the user's current tokens will be
revoked.
-Inherited Role Assignment Extension
------------------------------------
+Inherited Role Assignments
+--------------------------
-Keystone provides an optional extension that adds the 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 extension is disabled by default, but can be enabled by
-including the following in ``keystone.conf``:
+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 = True
+ enabled = False
+
+
+Endpoint Policy
+---------------
+
+The Endpoint Policy feature provides associations between service endpoints
+and policies that are already stored in the Identity server and referenced
+by a policy ID.
+
+Configure the endpoint policy backend driver in the ``[endpoint_policy]``
+section. For example:
+
+.. code-block:: ini
+
+ [endpoint_policy]
+ driver = sql
+
+See `API Specification for Endpoint Policy <http://specs.openstack.org/
+openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`_
+for the details of API definition.
+
+.. NOTE:: Support status for Endpoint Policy
+
+ *Experimental* (Juno)
+ *Stable* (Kilo)
+
+
+OAuth1 1.0a
+-----------
+
+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:
+
+1. Add the oauth1 driver to the ``[oauth1]`` section in ``keystone.conf``. For
+ example:
+
+.. code-block:: ini
+
+ [oauth1]
+ driver = sql
+
+2. Add the ``oauth1`` authentication method to the ``[auth]`` section in
+ ``keystone.conf``:
+
+.. code-block:: ini
+
+ [auth]
+ methods = external,password,token,oauth1
+
+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:
+
+.. code-block:: ini
+
+ WSGIPassAuthorization On
+
+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
+API definition.
+
+.. NOTE:: Support status for OAuth 1.0a
+
+ *Experimental* (Havana, Icehouse)
+ *Stable* (Juno)
+
+
+Revocation Events
+-----------------
+
+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
+
+See `API Specification for Revocation Events <https://specs.openstack.org/
+openstack/keystone-specs/api/v3/identity-api-v3-os-revoke-ext.html>`_ for
+the details of API definition.
+
+.. NOTE:: Support status for Revocation Events
+
+ *Experimental* (Juno)
+ *Stable* (Kilo)
Token Binding
@@ -1114,6 +1220,39 @@ If a response to ``list_{entity}`` call has been truncated, then the response
status code will still be 200 (OK), but the ``truncated`` attribute in the
collection will be set to ``true``.
+
+URL safe naming of projects and domains
+---------------------------------------
+
+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
+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
+including any of the reserverd characters specified in section 2.2 of
+`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
+
+When set to ``off`` (which is the default), no checking is done on the URL
+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.
+
Sample Configuration Files
--------------------------
@@ -1124,6 +1263,7 @@ files for each Server application.
* ``etc/keystone-paste.ini``
* ``etc/logging.conf.sample``
* ``etc/default_catalog.templates``
+* ``etc/sso_callback_template.html``
.. _`API protection with RBAC`:
@@ -1189,6 +1329,7 @@ are filtered out (e.g. user passwords).
List of object attributes:
* role:
+ * target.role.domain_id
* target.role.id
* target.role.name
@@ -1441,14 +1582,6 @@ as follows:
$ 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
-For additional examples using ``python-keystoneclient`` refer to
-`python-keystoneclient examples`_, likewise, for additional examples using
-``python-openstackclient``, refer to `python-openstackclient examples`_.
-
-.. _`python-keystoneclient examples`: cli_examples.html#using-python-keystoneclient-v2-0
-.. _`python-openstackclient examples`: cli_examples.html#using-python-openstackclient-v3
-
-
Removing Expired Tokens
=======================
@@ -1506,12 +1639,6 @@ The corresponding entries in the Keystone configuration file are:
user_tree_dn = ou=Users,dc=openstack,dc=org
user_objectclass = inetOrgPerson
- project_tree_dn = ou=Projects,dc=openstack,dc=org
- project_objectclass = groupOfNames
-
- role_tree_dn = ou=Roles,dc=openstack,dc=org
- role_objectclass = organizationalRole
-
The default object classes and attributes are intentionally simplistic. They
reflect the common standard objects according to the LDAP RFCs. However, in a
live deployment, the correct attributes can be overridden to support a
@@ -1539,14 +1666,6 @@ and you have only read access, in such case the configuration is:
user_allow_update = False
user_allow_delete = False
- project_allow_create = True
- project_allow_update = True
- project_allow_delete = True
-
- role_allow_create = True
- role_allow_update = True
- role_allow_delete = True
-
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:
@@ -1555,8 +1674,6 @@ look like:
[ldap]
user_filter = (memberof=CN=openstack-users,OU=workgroups,DC=openstack,DC=org)
- project_filter =
- role_filter =
In case that the directory server does not have an attribute enabled of type
boolean for the user, there is several configuration parameters that can be
@@ -1588,26 +1705,15 @@ specified classes in the LDAP module so you can configure them like:
.. code-block:: ini
[ldap]
- user_objectclass = person
- user_id_attribute = cn
- user_name_attribute = cn
- user_mail_attribute = mail
- user_enabled_attribute = userAccountControl
- user_enabled_mask = 2
- user_enabled_default = 512
- user_attribute_ignore = tenant_id,tenants
- project_objectclass = groupOfNames
- project_id_attribute = cn
- project_member_attribute = member
- project_name_attribute = ou
- project_desc_attribute = description
- project_enabled_attribute = extensionName
- project_attribute_ignore =
- role_objectclass = organizationalRole
- role_id_attribute = cn
- role_name_attribute = ou
- role_member_attribute = roleOccupant
- role_attribute_ignore =
+ 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
Debugging LDAP
--------------
@@ -1632,14 +1738,13 @@ Enabled Emulation
-----------------
Some directory servers do not provide any enabled attribute. For these servers,
-the ``user_enabled_emulation`` and ``project_enabled_emulation`` attributes
-have been created. They are enabled by setting their respective flags to True.
-Then the attributes ``user_enabled_emulation_dn`` and
-``project_enabled_emulation_dn`` may be set to specify how the enabled users
-and projects (tenants) are selected. These attributes work by using a
-``groupOfNames`` entry and adding whichever users or projects (tenants) 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:
+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:
.. code-block:: ini
@@ -1647,15 +1752,14 @@ example, this will mark any user who is a member of ``enabled_users`` as enabled
user_enabled_emulation = True
user_enabled_emulation_dn = cn=enabled_users,cn=groups,dc=openstack,dc=org
-The default values for user and project (tenant) enabled emulation DN is
-``cn=enabled_users,$user_tree_dn`` and ``cn=enabled_tenants,$project_tree_dn``
-respectively.
+The default values for user enabled emulation DN is
+``cn=enabled_users,$user_tree_dn``.
+
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
-``user_enabled_emulation_use_group_config`` and
-``project_enabled_emulation_use_group_config`` attributes to True.
+``user_enabled_emulation_use_group_config`` attribute to True.
Secure Connection
-----------------
@@ -1760,7 +1864,7 @@ 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
-``use_auth_pool`` to false. If a deployment wants to use a pool for those
+``use_auth_pool`` to false. If a deployment wants to use a pool for those
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
@@ -1805,3 +1909,16 @@ Connection pool configuration is part of the ``[ldap]`` configuration section:
# End user auth connection lifetime in seconds. (integer value)
auth_pool_connection_lifetime=60
+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"