From 3401d4103777564a91d584b9bc230037d4a78050 Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Fri, 19 Feb 2016 09:16:30 -0600 Subject: [PATCH] Docs: Keystone AD/LDAP cleanup This patch cleans up the Keystone AD/LDAP back end section a bit and adds an additional example where the LDAP back end is used as a read-only resource. Change-Id: I9b75d941d7aff4dcafd8e8f486e406455721340d --- .../install-guide/configure-keystone.rst | 95 +++++++++++++------ 1 file changed, 67 insertions(+), 28 deletions(-) diff --git a/doc/source/install-guide/configure-keystone.rst b/doc/source/install-guide/configure-keystone.rst index 8bdabb7dc8..c4eabf3e05 100644 --- a/doc/source/install-guide/configure-keystone.rst +++ b/doc/source/install-guide/configure-keystone.rst @@ -17,41 +17,80 @@ options. .. _Securing services with SSL certificates: configure-sslcertificates.html -Implementing LDAP (or AD) Back-Ends -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Implementing LDAP (or Active Directory) Back ends +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In many environments there may already be a LDAP (or Active Directory) service -available which already has Users, Groups and User-Group assignment data. -Keystone can be configured to make use of the LDAP service using -Domain-specific Back-End configuration. +Deployers that already have LDAP or Active Directory (AD) infrastructure +deployed can use the built-in Keystone support for those identity services. +Keystone can use the existing users, groups and user-group relationships to +handle authentication and access control in an OpenStack deployment. -While it is possible to set the Keystone Identity Back-End to use LDAP for -the Default domain, this is not recommended. It is a better practice to use -the Default domain for service accounts and to configure additional Domains -for LDAP services which provide general User/Group data. +.. note:: -Example implementation in user_variables.yml: + Although deployers can configure the default domain in Keystone to use LDAP + or AD identity back ends, **this is not recommended**. Deployers should + create an additional domain in Keystone and configure an LDAP/AD back end + for that domain. -keystone_ldap: - Users: - url: "ldap://10.10.10.10" - user: "root" - password: "secrete" - ... - Admins: - url: "ldap://20.20.20.20" - user: "root" - password: "secrete" - ... + This is critical in situations where the identity back end cannot + be reached due to network issues or other problems. In those situations, + the administrative users in the default domain would still be able to + authenticate to keystone using the default domain which is not backed by + LDAP or AD. -This will place two configuration files into /etc/keystone/domains/, both of -which will be configured to use the LDAP driver. +Deployers can add domains with LDAP back ends by adding variables in +``/etc/openstack_deploy/user_variables.yml``. For example, this dictionary will +add a new Keystone domain called ``Users`` that is backed by an LDAP server: - - keystone.Users.conf - - keystone.Admins.conf +.. code-block:: yaml -Each first level key entry is a domain name. Each entry below that are -key-value pairs for the 'ldap' section in the configuration file. + keystone_ldap: + Users: + url: "ldap://10.10.10.10" + user: "root" + password: "secrete" + +Adding the YAML block above will cause the Keystone playbook to create a +``/etc/keystone/domains/keystone.Users.conf`` file within each Keystone service +container that configures the LDAP-backed domain called ``Users``. + +Deployers can create more complex configurations that use LDAP filtering and +consume LDAP as a read-only resource. The following example shows how to apply +these configurations: + +.. code-block:: yaml + + keystone_ldap: + MyCorporation: + url: "ldaps://ldap.example.com" + user_tree_dn: "ou=Users,o=MyCorporation" + group_tree_dn: "cn=openstack-users,ou=Users,o=MyCorporation" + user_objectclass: "inetOrgPerson" + user_allow_create: "False" + user_allow_update: "False" + user_allow_delete: "False" + group_allow_create: "False" + group_allow_update: "False" + group_allow_delete: "False" + user_id_attribute: "cn" + user_name_attribute: "uid" + user_filter: "(groupMembership=cn=openstack-users,ou=Users,o=MyCorporation)" + +In the *MyCorporation* example above, Keystone will use the LDAP server as a +read-only resource. The configuration also ensures that Keystone filters the +list of possible users to the ones that exist in the +``cn=openstack-users,ou=Users,o=MyCorporation`` group. + +Horizon offers multi-domain support that can be enabled with an Ansible +variable during deployment: + +.. code-block:: yaml + + horizon_keystone_multidomain_support: True + +Enabling multi-domain support in Horizon will add the ``Domain`` input field on +the Horizon login page and it will add other domain-specific features in the +*Identity* section. More details regarding valid configuration for the LDAP Identity Back-End can be found in the `Keystone Developer Documentation`_ and the