Enable the Keystone LDAP back end in OpenStack

Configure OpenStack to use LDAP for identity management

OpenStack is open source software for building public and private clouds that provide an Infrastructure as a Service (IaaS) platform. Keystone is an OpenStack subproject that provides identity services, including user authentication and authorization, for the OpenStack family of projects. This article shows how to configure Keystone to use a Lightweight Directory Access Protocol (LDAP) server as its back end for identity services, instead of the default SQL back end.

Sahdev P. Zala (spzala@us.ibm.com), Software Engineer, IBM

Sahdev P. Zala photoSahdev P. Zala is a software engineer with the Software Group Standards Strategy organization at IBM. Sahdev is a contributor to the OpenStack project, with a current focus on Keystone development. Previously, he worked on developing IBM software for small and medium businesses and cross-product serviceability initiatives. He has authored IBM Redbooks, white papers, and technical documents on a variety of topics. Sahdev received a master's degree in computer science from North Carolina A&T State University, where his research focus was on high-performance computing and speech recognition.



Brad Topol (btopol@us.ibm.com), Distinguished Engineer, IBM

Brad Topol photoBrad Topol is an IBM distinguished engineer in the Software Group Standards Strategy organization. In his current role, Brad leads a development team that is focused on contributing to and improving OpenStack. He has also personally contributed to multiple OpenStack projects, including Keystone and DevStack. Over the years, Brad has been involved in advanced technology projects in the areas of product serviceability, problem determination, autonomic computing, content transcoding for mobile devices, and web services. He received a Ph.D. in computer science from the Georgia Institute of Technology in 1998.



17 September 2013

Also available in Chinese Russian Japanese

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 example:

ENABLED_SERVICES=key,n-api,n-crt,n-obj,n-cpu,n-net,n-cond,cinder,c-sch,
c-api,c-vol,n-sch,n-novnc,n-xvnc,n-cauth,horizon,mysql,rabbit,ldap

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:

KEYSTONE_CLEAR_LDAP=yes

Save and close localrc. Now run the stack.sh script from the devstack root directory:

./stack.sh

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

LDAP tree

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
The schema shown above the tree structure (with / indicating end of a line)

In the example LDAP tree in Figure 1, Users, UserGroups, Projects, and Roles each is its own subtree that uses a standard LDAP ObjectClass. In the Users subtree, for example, ObjectClass=inetOrgPerson.


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):

  1. In the [identity] section of keystone.conf, replace driver = keystone.identity.backends.sql.Identity with driver = keystone.identity.backends.ldap.Identity.
  2. 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:

./run_tests.sh _ldap_livetest.py

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:

./run_tests.sh

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.


Conclusion

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.

Resources

Learn

  • 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.
  • localrc: Read this page in the DevStack documentation for details on configuring the localrc user-settings file.
  • 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.
  • Explore Cloud computing on developerWorks, where you will find valuable community discussions and learn about new technical resources related to the cloud.

Get products and technologies

Discuss

  • Get involved in the developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Cloud computing on developerWorks


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Cloud digest

    Complete cloud software, infrastructure, and platform knowledge.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • Try SoftLayer Cloud

    Deploy public cloud instances in as few as 5 minutes. Try the SoftLayer public cloud instance for one month.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing, Security
ArticleID=945260
ArticleTitle=Enable the Keystone LDAP back end in OpenStack
publish-date=09172013