From 673edd8504cc07b0291b0bd65f137fc15b7769d5 Mon Sep 17 00:00:00 2001 From: daz Date: Tue, 23 Jun 2015 16:56:53 +1000 Subject: [PATCH] Convert other Identity files to RST Files converted: - Integrate Identity with LDAP - Use trusts - Configure Identity service for token binding - Caching layer - Integrate assignment back end with LDAP - Integrate Identity back end with LDAP - Secure the Identity service connection to an LDAP back end Change-Id: Ic51e1a677993eabaaa6316df61ec5517cfeb99a4 Implements: blueprint reorganise-user-guide --- .../source/identity_management.rst | 23 +- .../source/keystone_caching_layer.rst | 135 ++++++++++ ...tone_integrate_assignment_backend_ldap.rst | 148 +++++++++++ ...ystone_integrate_identity_backend_ldap.rst | 241 ++++++++++++++++++ .../source/keystone_integrate_with_ldap.rst | 173 +++++++++++++ ...ystone_secure_identity_to_ldap_backend.rst | 71 ++++++ .../source/keystone_token-binding.rst | 69 +++++ .../source/keystone_use_trusts.rst | 57 +++++ 8 files changed, 907 insertions(+), 10 deletions(-) create mode 100644 doc/admin-guide-cloud-rst/source/keystone_caching_layer.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_integrate_assignment_backend_ldap.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_integrate_identity_backend_ldap.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_integrate_with_ldap.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_secure_identity_to_ldap_backend.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_token-binding.rst create mode 100644 doc/admin-guide-cloud-rst/source/keystone_use_trusts.rst diff --git a/doc/admin-guide-cloud-rst/source/identity_management.rst b/doc/admin-guide-cloud-rst/source/identity_management.rst index d239f5d2b6..ea178d899e 100644 --- a/doc/admin-guide-cloud-rst/source/identity_management.rst +++ b/doc/admin-guide-cloud-rst/source/identity_management.rst @@ -247,16 +247,6 @@ resulting file would look like: "network:delete_dns_domain": "role:compute-user" } -.. TODO (DC) Convert the following common files and include(?) them as - sections: - /common/section_keystone_certificates-for-pki.xml - /common/section_keystone-ssl-config.xml - /common/section_keystone-external-auth.xml - /common/section_keystone_config_ldap.xml - identity/section_keystone-token-binding.xml - identity/section_keystone-trusts.xml - identity/section_caching-layer.xml - Service management ------------------ @@ -330,18 +320,31 @@ Here are a couple of examples: Domain B, if User B gets a token scoped to Domain B, the token also includes Role B. + .. include:: keystone_certificates_for_pki.rst .. include:: keystone_configure_with_SSL.rst .. include:: keystone_external_authentication.rst +.. include:: keystone_integrate_with_ldap.rst + +.. include:: keystone_token-binding.rst + +.. include:: keystone_use_trusts.rst + +.. include:: keystone_caching_layer.rst + .. toctree:: :hidden: keystone_certificates_for_pki.rst keystone_configure_with_SSL.rst keystone_external_authentication.rst + keystone_integrate_with_ldap.rst + keystone_token-binding.rst + keystone_use_trusts.rst + keystone_caching_layer.rst User CRUD ~~~~~~~~~ diff --git a/doc/admin-guide-cloud-rst/source/keystone_caching_layer.rst b/doc/admin-guide-cloud-rst/source/keystone_caching_layer.rst new file mode 100644 index 0000000000..62a9f32d2c --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_caching_layer.rst @@ -0,0 +1,135 @@ +.. :orphan: + +Caching layer +~~~~~~~~~~~~~ + +OpenStack Identity supports a caching layer that is above the +configurable subsystems (for example, token, assignment). OpenStack +Identity uses the +`dogpile.cache `__ +library which allows flexible cache back ends. The majority of the +caching configuration options are set in the ``[cache]`` section of the +:file:`keystone.conf` file. However, each section that has the capability to +be cached usually has a caching boolean value that toggles caching. + +So to enable only the token back end caching, set the values as follows: + +.. code-block:: ini + :linenos: + + [cache] + enabled=true + + [assignment] + caching=false + + [token] + caching=true + +.. note:: + + Since the Juno release, the default setting is enabled for subsystem + caching, but the global toggle is disabled. As a result, no caching + in available unless the global toggle for ``[cache]`` is enabled by + setting the value to ``true``. + +Caching for tokens and tokens validation +---------------------------------------- + +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 from the other systems +in OpenStack Identity. This option is set in the ``[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. + +Here is a list of actions that are affected by the cached time: getting +a new token, revoking tokens, validating tokens, checking v2 tokens, and +checking v3 tokens. + +The delete token API calls invalidate the cache for the tokens being +acted upon, as well as invalidating the cache for the revoked token list +and the validate/check token calls. + +Token caching is configurable independently of the ``revocation_list`` +caching. Lifted expiration checks from the token drivers to the token +manager. This ensures that cached tokens will still raise a +``TokenNotFound`` flag when expired. + +For cache consistency, all token IDs are transformed into the short +token hash at the provider and token driver level. Some methods have +access to the full ID (PKI Tokens), and some methods do not. Cache +invalidation is inconsistent without token ID normalization. + +Caching around assignment CRUD +------------------------------ + +The assignment 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 Identity service. This option is set in the +``[assignment]`` section of the configuration file. + +Currently ``assignment`` has caching for ``project``, ``domain``, and +``role`` specific requests (primarily around the CRUD actions). Caching +is currently not implemented on grants. The ``list`` methods are not +subject to caching. + +Here is a list of actions that are affected by the assignment: assign +domain API, assign project API, and assign role API. + +The create, update, and delete actions for domains, projects and roles +will perform proper invalidations of the cached methods listed above. + +.. note:: + + If a read-only ``assignment`` back end 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 ``[assignment]`` + section of the configuration file) or the global ``expiration_time`` + (set in the ``[cache]`` section of the configuration file) before it + is reflected. If this type of delay (when using a read-only + ``assignment`` back end) is an issue, it is recommended that caching + be disabled on ``assignment``. To disable caching specifically on + ``assignment``, in the ``[assignment]`` section of the configuration + set ``caching`` to ``False``. + +For more information about the different back ends (and configuration +options), see: + +- `dogpile.cache.backends.memory `__ + +- `dogpile.cache.backends.memcached `__ + + .. note:: + + The memory back end is not suitable for use in a production + environment. + +- `dogpile.cache.backends.redis `__ + +- `dogpile.cache.backends.file `__ + +- ``keystone.common.cache.backends.mongo`` + +Configure the Memcached back end example +---------------------------------------- + +The following example shows how to configure the memcached back end: + +.. code-block:: ini + :linenos: + + [cache] + + enabled = true + backend = dogpile.cache.memcached + backend_argument = url:127.0.0.1:11211 + +You need to specify the URL to reach the ``memcached`` instance with the +``backend_argument`` parameter. diff --git a/doc/admin-guide-cloud-rst/source/keystone_integrate_assignment_backend_ldap.rst b/doc/admin-guide-cloud-rst/source/keystone_integrate_assignment_backend_ldap.rst new file mode 100644 index 0000000000..766cca9298 --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_integrate_assignment_backend_ldap.rst @@ -0,0 +1,148 @@ +Integrate assignment back end with LDAP +--------------------------------------- + +When you configure the OpenStack Identity service to use LDAP servers, +you can split authentication and authorization using the *assignment* +feature. Integrating the assignment back end with LDAP allows +administrators to use projects (tenant), roles, domains, and role +assignments in LDAP. + +.. note:: + + Using LDAP as an assignment back end is not recommended. + +.. note:: + + The OpenStack Identity service does not support domain-specific + assignment back ends. + +.. important:: + + For OpenStack Identity assignments to access LDAP servers, you must + define the destination LDAP server in the :file:`keystone.conf` file. + For more information, see ?. + +.. TODO (DC) Add link to keystone_integrate_identity_with_ldap.rst + +**Integrating assignment back ends with LDAP** + +#. Enable the assignment driver. In the ``[assignment]`` section, set the + ``driver`` configuration key to + ``keystone.assignment.backends.sql.Assignment``: + + .. code-block:: ini + :linenos: + + [assignment] + #driver = keystone.assignment.backends.sql.Assignment + driver = keystone.assignment.backends.ldap.Assignment + +#. Create the organizational units (OU) in the LDAP directory, and define + their corresponding location in the ``keystone.conf`` file: + + .. code-block:: ini + :linenos: + + [ldap] + role_tree_dn = + role_objectclass = inetOrgPerson + + project_tree_dn = ou=Groups,dc=example,dc=org + project_objectclass = groupOfNames + + .. note:: + + These schema attributes are extensible for compatibility with + various schemas. For example, this entry maps to the groupOfNames + attribute in Active Directory: + + .. code:: ini + + project_objectclass = groupOfNames + +#. A read-only implementation is recommended for LDAP integration. These + permissions are applied to object types in the ``keystone.conf`` file: + + .. code-block:: ini + :linenos: + + [ldap] + role_allow_create = False + role_allow_update = False + role_allow_delete = False + + project_allow_create = False + project_allow_update = False + project_allow_delete = False + +#. Restart the OpenStack Identity service:: + + + # service keystone restart + + .. warning:: + + During service restart, authentication and authorization are + unavailable. + +**Additional LDAP integration settings.** + +Set these options in the :file:`/etc/keystone/keystone.conf` file for a +single LDAP server, or :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` +files for multiple back ends. + +Filters + Use filters to control the scope of data presented through LDAP. + + .. code-block:: ini + :linenos: + + [ldap] + project_filter = (member=cn=openstack-user,ou=workgroups, + dc=example,dc=org) + role_filter = + + .. warning:: + + Filtering method + +Assignment attribute mapping + Mask account status values (include any additional attribute + mappings) for compatibility with various directory services. + Superfluous accounts are filtered with user\_filter. + + Setting attribute ignore to list of attributes stripped off on + update. + + .. code-block:: ini + :linenos: + + [ldap] + role_id_attribute = cn + role_name_attribute = ou + role_member_attribute = roleOccupant + role_additional_attribute_mapping = + role_attribute_ignore = + + project_id_attribute = cn + project_name_attribute = ou + project_member_attribute = member + project_desc_attribute = description + project_enabled_attribute = enabled + project_domain_id_attribute = businessCategory + project_additional_attribute_mapping = + project_attribute_ignore = + +Enabled emulation + An alternative method to determine if a project is enabled or not is + to check if that project is a member of the emulation group. + + Use DN of the group entry to hold enabled projects when using + enabled emulation. + + .. code-block:: ini + :linenos: + + [ldap] + project_enabled_emulation = false + project_enabled_emulation_dn = false diff --git a/doc/admin-guide-cloud-rst/source/keystone_integrate_identity_backend_ldap.rst b/doc/admin-guide-cloud-rst/source/keystone_integrate_identity_backend_ldap.rst new file mode 100644 index 0000000000..d658ff4c52 --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_integrate_identity_backend_ldap.rst @@ -0,0 +1,241 @@ +Integrate Identity back end with LDAP +------------------------------------- + +The Identity back end contains information for users, groups, and group +member lists. Integrating the Identity back end with LDAP allows +administrators to use users and groups in LDAP. + +.. important:: + + For OpenStack Identity Service to access LDAP servers, you must + define the destination LDAP server in the ``keystone.conf`` file. + For more information, see ?. + +.. TODO (DC) Add link to keystone_integrate_identity_with_ldap.rst + +**Integrating an Identity back end with LDAP** + +#. Enable the LDAP Identity driver in the ``keystone.conf`` file. This + allows LDAP as an identity back end: + + .. code-block:: ini + :linenos: + + [identity] + #driver = keystone.identity.backends.sql.Identity + driver = keystone.identity.backends.ldap.Identity + +#. Create the organizational units (OU) in the LDAP directory, and define + the corresponding location in the :file:`keystone.conf` file: + + .. code-block:: ini + :linenos: + + [ldap] + user_tree_dn = ou=Users,dc=example,dc=org + user_objectclass = inetOrgPerson + + group_tree_dn = ou=Groups,dc=example,dc=org + group_objectclass = groupOfNames + + .. note:: + + These schema attributes are extensible for compatibility with + various schemas. For example, this entry maps to the person + attribute in Active Directory: + + .. code:: ini + + user_objectclass = person + +#. A read-only implementation is recommended for LDAP integration. These + permissions are applied to object types in the :file:`keystone.conf`: + + .. code-block:: ini + :linenos: + + [ldap] + user_allow_create = False + user_allow_update = False + user_allow_delete = False + + group_allow_create = False + group_allow_update = False + group_allow_delete = False + + Restart the OpenStack Identity service:: + + # service keystone restart + + .. warning:: + + During service restart, authentication and authorization are + unavailable. + +**Integrating Identity with multiple back ends** + +#. Set the following options in the :file:`/etc/keystone/keystone.conf` file: + + #. Enable the LDAP driver: + + .. code:: ini + + [identity] + #driver = keystone.identity.backends.sql.Identity + driver = keystone.identity.backends.ldap.Identity + + #. Enable domain-specific drivers: + + .. code:: ini + + [identity] + domain_specific_drivers_enabled = True + domain_config_dir = /etc/keystone/domains + +#. Restart the service:: + + # service keystone restart + +#. List the domains using the dashboard, or the OpenStackClient CLI. Refer + to the `Command List + `__ + for a list of OpenStackClient commands. + +#. Create domains using OpenStack dashboard, or the OpenStackClient CLI. + +#. For each domain, create a domain-specific configuration file in the + :file:`/etc/keystone/domains` directory. Use the file naming convention + :file:`keystone.DOMAIN_NAME.conf`, where DOMAIN\_NAME is the domain name + assigned in the previous step. + +.. note:: + + The options set in the + :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` file will + override options in the :file:`/etc/keystone/keystone.conf` file. + +#. Define the destination LDAP server in the + :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` file. For example: + + .. code-block:: ini + :linenos: + + [ldap] + url = ldap://localhost + user = dc=Manager,dc=example,dc=org + password = samplepassword + suffix = dc=example,dc=org + use_dumb_member = False + allow_subtree_delete = False + +#. Create the organizational units (OU) in the LDAP directories, and define + their corresponding locations in the + :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` file. For example: + + .. code-block:: ini + :linenos: + + [ldap] + user_tree_dn = ou=Users,dc=example,dc=org + user_objectclass = inetOrgPerson + + group_tree_dn = ou=Groups,dc=example,dc=org + group_objectclass = groupOfNames + + .. note:: + + These schema attributes are extensible for compatibility with + various schemas. For example, this entry maps to the person + attribute in Active Directory: + + .. code:: ini + + user_objectclass = person + +#. A read-only implementation is recommended for LDAP integration. These + permissions are applied to object types in the + :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` file: + + .. code:: ini + + [ldap] + user_allow_create = False + user_allow_update = False + user_allow_delete = False + + group_allow_create = False + group_allow_update = False + group_allow_delete = False + +#. Restart the OpenStack Identity service:: + + # service keystone restart + + .. warning:: + + During service restart, authentication and authorization are + unavailable. + +**Additional LDAP integration settings.** + +Set these options in the :file:`/etc/keystone/keystone.conf` file for a +single LDAP server, or :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` +files for multiple back ends. + +Filters + Use filters to control the scope of data presented through LDAP. + + .. code-block:: ini + :linenos: + + [ldap] + user_filter = (memberof=cn=openstack-users,ou=workgroups,dc=example,dc=org) + group_filter = + +Identity attribute mapping + Mask account status values (include any additional attribute + mappings) for compatibility with various directory services. + Superfluous accounts are filtered with ``user_filter``. + + Setting attribute ignore to list of attributes stripped off on + update. + + For example, you can mask Active Directory account status attributes + in the :file:`keystone.conf` file: + + .. code-block:: ini + :linenos: + + [ldap] + user_id_attribute = cn + user_name_attribute = sn + user_mail_attribute = mail + user_pass_attribute = userPassword + user_enabled_attribute = userAccountControl + user_enabled_mask = 2 + user_enabled_invert = false + user_enabled_default = 51 + user_default_project_id_attribute = + user_attribute_ignore = default_project_id,tenants + user_additional_attribute_mapping = + + group_id_attribute = cn + group_name_attribute = ou + group_member_attribute = member + group_desc_attribute = description + group_attribute_ignore = + group_additional_attribute_mapping = + +Enabled emulation + An alternative method to determine if a user is enabled or not is by + checking if that user is a member of the emulation group. + + Use DN of the group entry to hold enabled user when using enabled + emulation. + + .. code-block:: ini + :linenos: + + [ldap] + user_enabled_emulation = false + user_enabled_emulation_dn = false diff --git a/doc/admin-guide-cloud-rst/source/keystone_integrate_with_ldap.rst b/doc/admin-guide-cloud-rst/source/keystone_integrate_with_ldap.rst new file mode 100644 index 0000000000..2fe2dbde6d --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_integrate_with_ldap.rst @@ -0,0 +1,173 @@ +.. _integrate-identity-with-ldap: + +.. :orphan: + +Integrate Identity with LDAP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The OpenStack Identity service supports integration with existing LDAP +directories for authentication and authorization services. + +When the OpenStack Identity service is configured to use LDAP back ends, +you can split authentication (using the *identity* feature) and +authorization (using the *assignment* feature). + +The *identity* feature enables administrators to manage users and groups +by each domain or the OpenStack Identity service entirely. + +The *assignment* feature enables administrators to manage project role +authorization using the OpenStack Identity service SQL database, while +providing user authentication through the LDAP directory. + +.. important:: + + For OpenStack Identity service to access LDAP servers, you must + enable the ``authlogin_nsswitch_use_ldap`` boolean value for SELinux + on the Openstack Identity server. To enable and make the option + persistent across reboots:: + + # setsebool -P authlogin_nsswitch_use_ldap on + +Identity configuration is split into two separate back ends; identity +(back end for users and groups), and assignments (back end for domains, +projects, roles, role assignments). To configure Identity, set options +in the :file:`/etc/keystone/keystone.conf` file. See ? for Identity back end +configuration examples and ? for assignment back end configuration examples. +Modify these examples as needed. + +.. TODO (DC) Add links to keystone_integrate_identity_backend_ldap.rst and + keystone_integrate_assignment_backend_ldap.rst + +.. note:: + + Multiple back ends are supported. You can integrate the OpenStack + Identity service with a single LDAP server (configure both identity + and assignments to LDAP, or set identity and assignments back end + with SQL or LDAP), or multiple back ends using domain-specific + configuration files. + +To define the destination LDAP server +------------------------------------- + +Define the destination LDAP server in the :file:`keystone.conf` file: + +.. code-block:: ini + :linenos: + + [ldap] + url = ldap://localhost + user = dc=Manager,dc=example,dc=org + password = samplepassword + suffix = dc=example,dc=org + use_dumb_member = False + allow_subtree_delete = False + +.. note:: + + Configure ``dumb_member`` if you set ``use_dumb_member`` to true. + + .. code-block:: ini + :linenos: + + [ldap] + dumb_member = cn=dumb,dc=nonexistent + +Additional LDAP integration settings +------------------------------------ + +Set these options in the :file:`/etc/keystone/keystone.conf` file for a +single LDAP server, or :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf` +files for multiple back ends. + +**Query option** + +Use ``query_scope`` to control the scope level of data presented +(search only the first level or search an entire sub-tree) through LDAP. + +Use ``page_size`` to control the maximum results per page. A value of zero +disables paging. + +Use ``alias_dereferencing`` to control the LDAP dereferencing option for +queries. + +Use ``chase_referrals`` to override the system's default referral chasing +behavior for queries. + +.. code-block:: ini + :linenos: + + [ldap] + query_scope = sub + page_size = 0 + alias_dereferencing = default + chase_referrals = + +**Debug** + +Use ``debug_level`` to set the LDAP debugging level for LDAP calls. +A value of zero means that debugging is not enabled. + +.. code-block:: ini + :linenos: + + [ldap] + debug_level = 0 + +.. warning:: + + This value is a bitmask, consult your LDAP documentation for + possible values. + +**Connection pooling** + +Use ``use_pool`` to enable LDAP connection pooling. Configure +connection pool size, maximum retry, reconnect trials, timeout (-1 +indicates indefinite wait) and lifetime in seconds. + +.. code-block:: ini + :linenos: + + [ldap] + use_pool = true + pool_size = 10 + pool_retry_max = 3 + pool_retry_delay = 0.1 + pool_connection_timeout = -1 + pool_connection_lifetime = 600 + +**Connection pooling for end user authentication** + +Use ``use_auth_pool`` to enable LDAP connection pooling for end user +authentication. Configure connection pool size and lifetime in +seconds. + +.. code-block:: ini + :linenos: + + [ldap] + use_auth_pool = false + auth_pool_size = 100 + auth_pool_connection_lifetime = 60 + +When you have finished configuration, restart the OpenStack Identity +service:: + + # service keystone restart + +.. warning:: + + During service restart, authentication and authorization are + unavailable. + +.. include:: keystone_integrate_identity_backend_ldap.rst + +.. include:: keystone_integrate_assignment_backend_ldap.rst + +.. include:: keystone_secure_identity_to_ldap_backend.rst + +.. toctree:: + :hidden: + + keystone_integrate_identity_backend_ldap.rst + keystone_integrate_assignment_backend_ldap.rst + keystone_secure_identity_to_ldap_backend.rst diff --git a/doc/admin-guide-cloud-rst/source/keystone_secure_identity_to_ldap_backend.rst b/doc/admin-guide-cloud-rst/source/keystone_secure_identity_to_ldap_backend.rst new file mode 100644 index 0000000000..fe7884eff5 --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_secure_identity_to_ldap_backend.rst @@ -0,0 +1,71 @@ +Secure the OpenStack Identity service connection to an LDAP back end +-------------------------------------------------------------------- + +The Identity service supports the use of TLS to encrypt LDAP traffic. +Before configuring this, you must first verify where your certificate +authority file is located. For more information, see ?. + +.. TODO (DC) figure out how to reference + keystone_integrate_identity_with_ldap.rst with orphan tag + +Once you verify the location of your certificate authority file: + +**Configuring TLS encryption on LDAP traffic** + +#. Open the :file:`/etc/keystone/keystone.conf` configuration file. + +#. Find the ``[ldap]`` section. + +#. In the ``[ldap]`` section, set the ``use_tls`` configuration key to + ``True``. Doing so will enable TLS. + +#. Configure the Identity service to use your certificate authorities file. + To do so, set the ``tls_cacertfile`` configuration key in the ``ldap`` + section to the certificate authorities file's path. + + .. note:: + + You can also set the ``tls_cacertdir`` (also in the ``ldap`` + section) to the directory where all certificate authorities files + are kept. If both ``tls_cacertfile`` and ``tls_cacertdir`` are set, + then the latter will be ignored. + +#. Specify what client certificate checks to perform on incoming TLS + sessions from the LDAP server. To do so, set the ``tls_req_cert`` + configuration key in the ``[ldap]`` section to ``demand``, ``allow``, or + ``never``: + + - ``demand`` + A certificate will always be requested from the LDAP + server. The session will be terminated if no certificate is provided, + or if the certificate provided cannot be verified against the + existing certificate authorities file. + + - ``allow`` + A certificate will always be requested from the LDAP + server. The session will proceed as normal even if a certificate is + not provided. If a certificate is provided but it cannot be verified + against the existing certificate authorities file, the certificate + will be ignored and the session will proceed as normal. + + - ``never`` + A certificate will never be requested. + +On distributions that include openstack-config, you can configure TLS +encryption on LDAP traffic by running the following commands instead:: + + # openstack-config --set /etc/keystone/keystone.conf \ + ldap use_tls True + # openstack-config --set /etc/keystone/keystone.conf \ + ldap tls_cacertfile ``CA_FILE`` + # openstack-config --set /etc/keystone/keystone.conf \ + ldap tls_req_cert ``CERT_BEHAVIOR`` + +Where: + +- ``CA_FILE`` is the absolute path to the certificate authorities file + that should be used to encrypt LDAP traffic. + +- ``CERT_BEHAVIOR`` specifies what client certificate checks to perform + on an incoming TLS session from the LDAP server (``demand``, + ``allow``, or ``never``). diff --git a/doc/admin-guide-cloud-rst/source/keystone_token-binding.rst b/doc/admin-guide-cloud-rst/source/keystone_token-binding.rst new file mode 100644 index 0000000000..63783f3d4b --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_token-binding.rst @@ -0,0 +1,69 @@ +.. :orphan: + +Configure Identity service for token binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Token binding embeds information from an external authentication +mechanism, such as a Kerberos server or X.509 certificate, inside a +token. By using token binding, a client can enforce the use of a +specified external authentication mechanism with the token. This +additional security mechanism ensures that if a token is stolen, for +example, it is not usable without external authentication. + +You configure the authentication types for a token binding in the +:file:`keystone.conf` file: + +.. code-block:: ini + :linenos: + + [token] + bind = kerberos + +or + +.. code-block:: ini + :linenos: + + [token] + bind = x509 + +Currently ``kerberos`` and ``x509`` are supported. + +To enforce checking of token binding, set the ``enforce_token_bind`` +option to one of these modes: + +- ``disabled`` + Disables token bind checking. + +- ``permissive`` + Enables bind checking. If a token is bound to an unknown + authentication mechanism, the server ignores it. The default is this + mode. + +- ``strict`` + Enables bind checking. If a token is bound to an unknown + authentication mechanism, the server rejects it. + +- ``required`` + Enables bind checking. Requires use of at least authentication + mechanism for tokens. + +- ``kerberos`` + Enables bind checking. Requires use of kerberos as the authentication + mechanism for tokens: + + .. code-block:: ini + :linenos: + + [token] + enforce_token_bind = kerberos + +- ``x509`` + Enables bind checking. Requires use of X.509 as the authentication + mechanism for tokens: + + .. code-block:: ini + :linenos: + + [token] + enforce_token_bind = x509 diff --git a/doc/admin-guide-cloud-rst/source/keystone_use_trusts.rst b/doc/admin-guide-cloud-rst/source/keystone_use_trusts.rst new file mode 100644 index 0000000000..b941ed1ff0 --- /dev/null +++ b/doc/admin-guide-cloud-rst/source/keystone_use_trusts.rst @@ -0,0 +1,57 @@ +.. :orphan: + +Use trusts +~~~~~~~~~~ + +OpenStack Identity manages authentication and authorization. A trust is +an OpenStack Identity extension that enables delegation and, optionally, +impersonation through ``keystone``. A trust extension defines a +relationship between: + +**Trustor** + The user delegating a limited set of their own rights to another user. + +**Trustee** + The user trust is being delegated to, for a limited time. + + The trust can eventually allow the trustee to impersonate the trustor. + For security reasons, some safeties are added. For example, if a trustor + loses a given role, any trusts the user issued with that role, and the + related tokens, are automatically revoked. + +The delegation parameters are: + +**User ID** + The user IDs for the trustor and trustee. + +**Privileges** + The delegated privileges are a combination of a tenant ID and a + number of roles that must be a subset of the roles assigned to the + trustor. + + If you omit all privileges, nothing is delegated. You cannot + delegate everything. + +**Delegation depth** + Defines whether or not the delegation is recursive. If it is + recursive, defines the delegation chain length. + + Specify one of the following values: + + - ``0``. The delegate cannot delegate these permissions further. + + - ``1``. The delegate can delegate the permissions to any set of + delegates but the latter cannot delegate further. + + - ``inf``. The delegation is infinitely recursive. + +**Endpoints** + A list of endpoints associated with the delegation. + + This parameter further restricts the delegation to the specified + endpoints only. If you omit the endpoints, the delegation is + useless. A special value of ``all_endpoints`` allows the trust to be + used by all endpoints associated with the delegated tenant. + +**Duration** + (Optional) Comprised of the start time and end time for the trust.