Platform9 Blog

OpenStack Keystone Federation Setup

As enterprises get more comfortable with the idea of hybrid cloud and multi-clouds, it has become critical to seamlessly manage user identities, and provide access to resources, across multiple clouds. Enterprises are using federated identity, along with single sign-on, to easily onboard users to the cloud. OpenStack Keystone federation can be set up by using providers like SAML, OAuth and OpenID Connect. This blog will provide an overview on how to configure Keystone with federated identity. The steps for Service Provider Keystone can also be used to enable single sign-on and authenticate with ADFS, Okta etc. 

What is Keystone Federation?

In a standard OpenStack setup, users authenticate against the identity APIs, usually implemented by the Keystone service. With federated Keystone, the options for authentication are greatly increased since it outsources that responsibility to an external Identity Provider (IdP). The Service Provider Keystone (SP) can instead just focus on managing access to resources on the cloud where it resides. As a result, a specific group of users in a trusted IdP service can access the cloud services without needing explicit accounts on the SP.

All that the SP Keystone really needs to know is the identity of the authenticated user plus any information required to map OpenStack-specific roles and projects to that user. Determining which roles to apply to a user is often based on group membership, such as dev, support etc. This approach makes the SP Keystone agnostic to the authentication method. It can even be configured to discover and use multiple IdP. Conversely, a single IdP can serve multiple SPs in different regions of a multi-region cloud setup.

Benefits of a Federated Setup

A federated identity setup provides a way to securely use existing credentials to access cloud resources such as servers and databases, across multiple authorized clouds, without having to create additional identities or login multiple times. The credentials are created and managed by the user’s Identity Provider. This reduces the risk associated with creating and securing credentials, and deploying them multiple times on different clouds.

Federated identity enables single sign-on for the users and makes it easier to remember passwords, and subsequently requires fewer password resets. The IdPs manage user identities and passwords so that OpenStack Keystone does not have to.


To enable Keystone federation, the following steps are needed.

  1. Configure both the IdP and SP Keystone services to run under Apache and use SAML.
  2. Configure the Keystone IdP to specify how the IdP Keystone will authenticate users, either through its own SQL database or by calling other directory services like AD or LDAP.  This step will also list the SPs so that the IdP knows to trust the authentication request from those SPs.
  3. Configure the Keystone SP to specify the location of one or more IdP and setup a mapping of the remote attributes returned by the IdP to the SP’s local group and role attributes.
  4. Configure Horizon for Single Sign-On (SSO). Optionally, Horizon can also be configured to enable web-based single sign-on.

Configure Keystone to run under Apache and enable Federation

The Keystone service requires a plugin, e.g. Shibboleth or Ipsilon, to integrate with federated SAML identity providers. To use this plugin, Keystone must be run under Apache. The steps to configure this setup are beyond the scope of this blog but detailed documentation is available here .

To enable the federation extension, update the configurations as follows

  • Add the federation extension driver to the [federation] section in the keystone.conf file

  • Add the saml2 authentication method to the [auth] section in the keystone.conf file

methods = external,password,token,saml2,oidc
saml2 = keystone.auth.plugins.mapped.Mapped
  • Add the federation_extension middleware to the api_v3 pipeline in keystone-paste.ini (enabled by default in OpenStack Liberty release). This must be added after json_body and before the last entry in the pipeline

pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension federation_extension service_v3
  • Create the federation extension tables if using the provided SQL backend

./bin/keystone-manage db_sync --extension federation

Configure the Keystone Identity Provider

This setup is required only when configuring OpenStack Keystone to act as the Identity Provider to another Keystone instance that is acting as Service Provider. Otherwise skip below to the section on Configuring the Keystone Service Provider.

  • To enable Keystone services to trust each other, they would have to share secure certificates. The first step is to generate a self-signed cert-key pair.  The IdP will share the resulting certificate with its SPs (through the IdP metadata), and will sign all the outgoing SAML assertions with the key.

$ openssl req -x509 -newkey rsa:2048 -keyout /etc/keystone/ssl/idpkey.pem -out /etc/keystone/ssl/idpcert.pem -days 9999 -nodes</span>

$ ls /etc/keystone/ssl/

certs  idpcert.pem  idpkey.pem  private
  • With the certificates generated, and the federation extension enabled from the previous step, update the SAML configuration to configure keystone

# /etc/keystone/keystone.conf






  • With this configuration, generate the IdP metadata that will be shared with the SP Keystone

keystone-manage saml_idp_metadata > /etc/keystone/keystone_idp_metadata.xml
  • Lastly, setup the keystone SP in the IdP – This step will inform the IdP about the URL to use when creating a SAML assertion for the SP.

$ curl -s -X PUT -H "X-Auth-Token: $OS_TOKEN" -H "Content-Type: application/json" -d '{"service_provider": {"auth_url":"http://${sp_keystone}:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth",
"sp_url": "https://${sp_keystone}:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}}' http://localhost:5000/v3/OS-FEDERATION/service_providers/sp_name | python -mjson.tool

Configure the Keystone Service Provider

  • Add the IdP Entity ID and metadata to the keystone SP by updating the configuration in /etc/shibboleth/shibboleth2.xml:
 <ApplicationDefaults entityID="https://<sp_ip or sp_hostname>/keystone">
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="false" cookieProps="https">
            <SSO entityID="https://<idp-host>/keystone/v3/OS-FEDERATION/saml2/idp">
                SAML2 SAML1
  • Add the IdP’s metadata provider – Loads and trusts a metadata file that describes an IdP and how to communicate with it
<MetadataProvider type="XML" validate="true" file="/etc/keystone/keystone_idp_metadata.xml"/>
  • Add attribute mappings to the attribute-map.xml file. This takes attributes from the incoming SAML assertion and translates them to parameters that are exposed to keystone as CGI environment variables on the wsgi request.
<Attribute name="openstack_user" id="openstack_user"/>
<Attribute name="openstack_roles" id="openstack_roles"/>
<Attribute name="openstack_project" id="openstack_project"/>
  • Upload the keystone mapping. This will map the remote attributes sent by the SP to the local attributes in the IdP
    "mapping": {
        "rules": [  {
                "local": [
                    {     "user": { "name": "{0}"    }  },
                    {     "group": { "id": "1234"    }   }
                "remote": [
                    { "type": "openstack_user",
                        "any_one_of": [""]     }
                ]      }
        ]  }

This setup can now be tested to get a unscoped token from the Identity Provider.

With this series of steps, the Keystone service provider can now authenticate via an external Identity Provider, that can possibly be another Keystone service. Typically, the OpenStack Horizon service is also setup to enable web single sign-on. In this follow up blog, we’ve discussed how to configure OpenStack Keystone single sign-on

If the enterprise requirements are to configure authentication with directory services such as LDAP, AD or ADFS, then this federation setup may not be necessary. See these blogs to configure Keystone with the popular Directory Services:
Keystone Authentication using LDAP
Keystone Authentication using AD
Keystone Authentication using ADFS


You may also enjoy

Announcing the Industry’s Only SaaS Managed Bare Metal Orchestration Platform

By Rohan Shah

How To Set Up OpenEBS on Kubernetes Using Platform9

By Piyush Katira

The browser you are using is outdated. For the best experience please download or update your browser to one of the following: