Enable the Keystone LDAP back end in OpenStack
Configure OpenStack to use LDAP for identity management
The open source OpenStack project provides an Infrastructure as a Service (IaaS) layer for building public and private clouds. Corporations, service providers, value-added resellers, small and mid-sized businesses, researchers, and global data centers all use OpenStack to deploy large-scale private or public clouds.
Lightweight Directory Access Protocol (LDAP) is a client/server protocol for accessing and managing directory information. Many enterprise applications use LDAP as the foundation for user authentication. (Implementations of LDAP include IBM® Tivoli® Directory Server, Microsoft® Active Directory, and OpenLDAP.) This article shows how to get an example integrated OpenStack/LDAP environment up and running quickly and correctly. Learn how to:
- Install an LDAP server by using DevStack, a tool for building OpenStack development environments.
- Configure Keystone to use the installed LDAP server through Keystone's LDAP identity driver.
- Populate the LDAP server with a Keystone-compliant tree structure.
- Use Keystone's unit-testing library to test your LDAP-based Keystone service.
Also, learn how to configure Keystone, without using DevStack, to use an LDAP server that's already running in a production environment.
Setting up an LDAP back end with DevStack
As of the April 2013 Grizzly release of OpenStack, you can set LDAP as the Keystone back end through the standard OpenStack development environment installation tool, DevStack. DevStack is a well-maintained and documented shell script for building complete OpenStack development environments.
Download DevStack and create a file named localrc in the devstack
root directory. Configure user customizations for OpenStack in localrc. To
enable DevStack to install an LDAP server on your behalf, add
ldap to the list of enabled services in localrc. For
You must also add the following line to localrc to inform DevStack that you want Keystone to use its LDAP back-end identity driver:
KEYSTONE_IDENTITY_BACKEND = ldap
If you want DevStack to clear out an existing Keystone LDAP tree and start fresh, add this line to the localrc file:
Save and close localrc. Now run the stack.sh script from the devstack root directory:
After the script finishes, you can see that:
- OpenLDAP was installed.
- Keystone was configured to use its LDAP back-end identity driver.
- An initial Keystone LDAP tree was created that uses the data in
devstack\files\ldap\openstack.ldif, shown in Listing 1:
Listing 1. Contents of openstack.ldif
dn: dc=openstack,dc=org dc: openstack objectClass: dcObject objectClass: organizationalUnit ou: openstack dn: ou=Groups,dc=openstack,dc=org objectClass: organizationalUnit ou: Groups dn: ou=Users,dc=openstack,dc=org objectClass: organizationalUnit ou: Users dn: ou=Roles,dc=openstack,dc=org objectClass: organizationalUnit ou: Roles dn: ou=Projects,dc=openstack,dc=org objectClass: organizationalUnit ou: Projects dn: cn=9fe2ff9ee4384b1894a90878d3e92bab,ou=Roles,dc=openstack,dc=org objectClass: organizationalRole ou: _member_ cn: 9fe2ff9ee4384b1894a90878d3e92bab
The example schema used by the Keystone LDAP back-end identity driver assumes the tree structure that's shown in Figure 1:
Figure 1. Example schema used by the Keystone LDAP back-end identity driver
In the example LDAP tree in Figure 1,
each is its own subtree that uses a standard LDAP
ObjectClass. In the
Users subtree, for example,
Configuring a production Keystone instance to use an existing LDAP server
If LDAP is already installed in your environment — and you installed a Keystone instance without using DevStack — you can directly reconfigure Keystone to use its LDAP back-end identity driver instead of the default SQL identity driver. To do that, modify values in the keystone.conf file (located by default in the /etc/keystone directory):
- In the
[identity]section of keystone.conf, replace
driver = keystone.identity.backends.sql.Identitywith
driver = keystone.identity.backends.ldap.Identity.
- Update the
[ldap]section to reflect your LDAP server configuration. Listing 2 shows an example:
Listing 2. Example LDAP settings in the keystone.conf file
[ldap] url = ldap://localhost user = dc=Manager,dc=openstack,dc=org password = yourpassword suffix = dc=openstack,dc=org user_tree_dn = ou=Users,dc=openstack,dc=org user_objectclass = inetOrgPerson user_id_attribute = cn user_mail_attribute = mail tenant_tree_dn = ou=Projects,dc=openstack,dc=org tenant_objectclass = groupOfNames tenant_id_attribute = cn tenant_desc_attribute = description use_dumb_member = True role_tree_dn = ou=Roles,dc=openstack, dc=org role_objectclass = organizationalRole role_id_attribute = cn role_member_attribute = roleOccupant
Note: Updating keystone.conf directly doesn't work if you're using DevStack, because DevStack automatically generates a new keystone.conf file every time that you run the stack.sh script.
Unit testing LDAP code
Keystone provides several files for unit testing an LDAP-based Keystone service. These files reside by default in /opt/stack/keystone/tests, except for the run_tests.sh file, which is in the /opt/stack/keystone/ directory. The files are:
- tests_backend.py: Contains tests that apply to both SQL and LDAP back ends.
- test_backend_ldap.py: Contains tests that are specific to LDAP.
- run_tests.sh: Runs a full regression test. Always run this file before updating your code.
- _ldap_livetest.py: Developers who are making LDAP-specific code changes should test the changes with a live LDAP by running the code in this file. This test assumes that an LDAP server (for example, OpenLDAP) is installed in your development environment.
- backend_liveldap.conf: Provides configuration data that is needed to run the live LDAP test. If you installed LDAP by using DevStack, you can use this file as-is by setting the correct password value. If you have a different LDAP configuration, ensure that this file's configuration data reflects your LDAP configuration.
- backend_ldap.conf: Provides configuration data that is needed to run a full regression test without an LDAP server.
Next are some testing examples. Change to your Keystone installation directory (the default is /opt/stack/keystone/) before you run your tests.
Live LDAP test
To run the live tests for LDAP:
Listing 3 shows example output for the live LDAP test:
Listing 3. Example output from live LDAP testing
LiveLDAPIdentity test_add_duplicate_role_grant OK test_add_role_grant_to_user_and_project_404 SKIP test_add_role_to_user_and_project_404 OK ................. ................. test_wrong_ldap_scope OK Slowest 5 tests took 11.49 secs: 2.99 LiveLDAPIdentity.test_create_user_invalid_name_fails 2.83 LiveLDAPIdentity.test_create_user_invalid_enabled_type_string 2.10 LiveLDAPIdentity.test_delete_role_with_user_and_group_grants 2.07 LiveLDAPIdentity.test_delete_user_with_project_association 1.49 LiveLDAPIdentity.test_user_filter ---------------------------------------------------------------------- Ran 142 tests in 97.297s OK (SKIP=29)
Full regression test
To run the full set of regression tests:
Listing 4 shows example output for the regression tests:
Listing 4. Example output from regression testing
AuthBadRequests test_authenticate_blank_auth OK test_authenticate_blank_request_body OK test_authenticate_invalid_auth_content OK ................. ................. MiddlewareTest test_mask_password OK test_middleware_bad_request OK test_middleware_exception_error OK test_middleware_local_config OK test_middleware_request OK test_middleware_response OK test_middleware_type_error OK Slowest 5 tests took 21.66 secs: 5.57 TestAuthJSON.test_user_and_group_roles_scoped_token 5.35 Kc11TestCase.test_admin_requires_adminness 4.04 KcEssex3TestCase.test_admin_requires_adminness 3.81 KcMasterTestCase.test_admin_requires_adminness 2.88 IdentityTestCase.test_filtered_role_assignments ---------------------------------------------------------------------- Ran 1363 tests in 315.451s OK (SKIP=82)
At present, the regression tests for LDAP use a fake LDAP server, so when you develop for LDAP it's important to run the live LDAP tests.
Keystone provides identity services for all OpenStack projects. In addition to the default SQL back end, Keystone supports LDAP and pluggable authentication modules. This article showed how to enable LDAP as a Keystone back end by either installing a new LDAP server or configuring Keystone to use an existing one. An upcoming feature in Keystone will provide for separating authentication from authorization, thereby enabling easier integration with a production LDAP instance.
- OpenStack: Visit the OpenStack website to learn more about OpenStack software.
- DevStack: Find out more about DevStack and see how to clone it from the GitHub repository.
- Keystone: Learn more about the identity-services project for OpenStack.
- Configure the Identity Service for an LDAP Backend: This page in the OpenStack Compute Administration Guide discusses the nuances of modifying Keystone directly to accommodate an LDAP back end.
- "Contribute your code to OpenStack" (Sheng Bo Hou, developerWorks, March 2013): Find out how you can help to enhance the OpenStack project.
- IBM Tivoli Directory Server: Download an evaluation version of IBM's LDAP implementation.