Deploying domain-specific identity drivers in OpenStack keystone

As of the Juno release, Keystone supports the ability to back each identity domain with a distinct driver configuration. So, for example, you can back one domain with LDAP, one with your own proprietary driver, and all the rest with keystone's default SQL backend.

This has previously been nicknamed multi-domain drivers, although the official documentation refers to the approach as domain-specific drivers, and so does IBM's documentation. (Be sure to checkout those docs as well if you're interested in this feature!)


When deploying keystone with domain-specific identity backends, you're probably going to be dealing with the following constraints:

  1. Service users need to be in the Default domain because not all services support v3 authentication prior to Liberty.

  2. Heat needs authorization to fully manage users and projects in an arbitrary domain because it needs to create temporary users for use with the /v3/trusts API.

  3. Keystone's default [identity] driver (in keystone.conf) needs to use SQL so that newly created domains will be backed by SQL identity, whereas LDAP-backed domains can be configured as the one-off exceptions.


  • The Default domain is backed by SQL, so services can continue authenticating using the v2.0 API without specifying a domain (remember, v2 is not domain-aware).

  • A new domain, named Users, is backed by LDAP, so your users must use v3 to authenticate, and specify a domain name (or ID) during authentication.

  • A new domain, named Heat, is backed by SQL, so heat has a place where it can freely create users.

  • Any other domains you create in the future will be automatically backed by SQL (unless you choose to drop a new domain-specific driver configuration for them and back them with something else — such as another LDAP server).

Configuring keystone

Configure keystone to use domain-specific identity backends in /etc/keystone/keystone.conf. This will trigger keystone to load configuration files from domain_config_dir:

domain_specific_drivers_enabled = True
domain_config_dir = /etc/keystone/domains

Configure the default [identity] driver in keystone.conf to be SQL. This will ensure that any domains which do not have a domain-specific configuration will be backed by SQL:

# If using the Liberty release or newer,
# just use "driver = sql" instead.
driver = keystone.identity.backends.sql.Identity

Then move your existing [ldap] configuration section from keystone.conf into a new file (creating the domains/ directory you just referenced above, if necessary):


You'll also need to set the [identity] driver for this domain (in your new keystone.Users.conf) to use LDAP, instead of your deployment's default (SQL):

# If using the Liberty release or newer,
# just use "driver = ldap" instead.
driver = keystone.identity.backends.ldap.Identity

Create that Users domain which you just referenced so that your domain-specific configuration file will be utilized:

$ openstack --os-identity-api-version=3 domain create Users

When creating service users, you'll create them in the Default domain. You won't be creating real users, because they're already stored in LDAP (rather, you'll be creating them in your directory instead of through keystone).

Testing keystone

You should then be able to start keystone at this point and authenticate normally as either a service user in the Default domain or an LDAP user in the Users. Not bad for what amounts to refactoring your configuration!

Configuring heat

Now, create a new, arbitrary domain for use by heat:

$ openstack --os-identity-api-version=3 domain create Heat

Configure /etc/heat/heat.conf to use the new domain:

stack_user_domain_id = <domain ID returned by above operation>

And I'll assume that the stack_domain_admin and stack_domain_admin_password already exist, but you'll need to assign that user an appropriate domain-level role assignment on the domain you just created, and revoke any previous role assignments (such as on the default domain). Remember, if you use the admin role, it'll give that heat user "root-ish" control of OpenStack!

Testing heat

You should be able to authenticate with the following environment variables:


... to create a user in the new domain you created:

$ openstack --os-identity-api-version=3 user create <new username> --domain=Heat --password=<new password for foobar>

And if that test works, then Heat should be good to go! (Don't forget to cleanup that test user you just created!)

Special thanks to Boris Bobrov (breton) for inquiring about a major inaccuracy in the original version of this article. Thank you!