openstack
/
keystone
Code Issues Proposed changes
keystone/doc/source/configure_federation.rst

11 KiB
Raw Blame History

Configuring Keystone for Federation

Definitions

  • `Service Provider (SP)`: provides a service to an end-user.
  • `Identity Provider (IdP)`: service that stores information about users and groups.
  • `SAML assertion`: contains information about a user as provided by an IdP.

Prerequisites

This approach to federation supports Keystone as a Service Provider, consuming SAML assertions issued by an external Identity Provider.

Federated users are not mirrored in the Keystone identity backend (for example, using the SQL driver). The external Identity Provider is responsible for authenticating users, and communicates the result of authentication to Keystone using SAML assertions. Keystone maps the SAML assertions to Keystone user groups and assignments created in Keystone.

The following configuration steps were performed on a machine running Ubuntu 12.04 and Apache 2.2.22.

To enable federation, you'll need to:

  1. Run Keystone under Apache, rather than using keystone-all.
  2. Configure Apache to use a federation capable authentication method.
  3. Enable OS-FEDERATION extension.

Configure Apache HTTPD for mod_shibboleth

Follow the steps outlined at: Running Keystone in HTTPD.

You'll also need to install Shibboleth, for example:

$ apt-get install libapache2-mod-shib2

Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow:

Add WSGIScriptAlias directive to your vhost configuration:

WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1

Make sure you add two <Location> directives to the wsgi-keystone.conf:

<Location /Shibboleth.sso>
    SetHandler shib
</Location>

<LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/saml2/auth>
    ShibRequestSetting requireSession 1
    AuthType shibboleth
    ShibRequireSession On
    ShibRequireAll On
    ShibExportAssertion Off
    Require valid-user
</LocationMatch>

Note

saml2 may be different in your deployment, but do not use a wildcard value. Otherwise every federated protocol will be handled by Shibboleth.

Enable the Keystone virtual host, for example:

$ a2ensite wsgi-keystone.conf

Enable the ssl and shib2 modules, for example:

$ a2enmod ssl
$ a2enmod shib2

Restart Apache, for example:

$ service apache2 restart

Configure Apache to use a federation capable authentication method

There are many ways to configure Federation in the Apache HTTPD server. Shibboleth is the only one documented so far.

Follow the steps outlined at: Setup Shibboleth.

Enable the OS-FEDERATION extension

Follow the steps outlined at: Enabling Federation Extension.

Configuring Federation

Now that the Identity Provider and Keystone are communicating we can start to configure the OS-FEDERATION extension.

  1. Add local Keystone groups and roles
  2. Add Identity Provider(s), Mapping(s), and Protocol(s)

Create Keystone groups and assign roles

As mentioned earlier, no new users will be added to the Identity backend, but the Identity Service requires group-based role assignments to authorize federated users. The federation mapping function will map the user into local Identity Service groups objects, and hence to local role assignments.

Thus, it is required to create the necessary Identity Service groups that correspond to the Identity Provider's groups; additionally, these groups should be assigned roles on one or more projects or domains.

You may be interested in more information on group management and role assignments, both of which are exposed to the CLI via python-openstackclient.

Add Identity Provider(s), Mapping(s), and Protocol(s)

To utilize federation the following must be created in the Identity Service:

  • Identity Provider
  • Mapping
  • Protocol

More information on OS-FEDERATION can be found here.

Identity Provider

Create an Identity Provider object in Keystone, which represents the Identity Provider we will use to authenticate end users.

More information on identity providers can be found here.

Mapping

A mapping is a list of rules. The only Identity API objects that will support mapping are groups and users.

Mapping adds a set of rules to map federation protocol attributes to Identity API objects. An Identity Provider has exactly one mapping specified per protocol.

Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol.

More information on mapping can be found here.

Protocol

A protocol contains information that dictates which Mapping rules to use for an incoming request made by an IdP. An IdP may have multiple supported protocols.

Add Protocol object and specify the mapping id you want to use with the combination of the IdP and Protocol.

Performing federated authentication

  1. Authenticate externally and generate an unscoped token in Keystone
  2. Determine accessible resources
  3. Get a scoped token

Get an unscoped token

Unlike other authentication methods in the Identity Service, the user does not issue an HTTP POST request with authentication data in the request body. To start federated authentication a user must access the dedicated URL with Identity Provider's and Protocol's identifiers stored within a protected URL. The URL has a format of: /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth.

In this instance we follow a standard SAML2 authentication procedure, that is, the user will be redirected to the Identity Provider's authentication webpage and be prompted for credentials. After successfully authenticating the user will be redirected to the Service Provider's endpoint. If using a web browser, a token will be returned in XML format.

In the returned unscoped token, a list of Identity Service groups the user belongs to will be included.

More information on getting an unscoped token can be found here.

Example cURL

Note that the request does not include a body. The following url would be considered protected by mod_shib and Apache, as such a request made to the URL would be redirected to the Identity Provider, to start the SAML authentication procedure.

$ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth

Determine accessible resources

By using the previously returned token, the user can issue requests to the list projects and domains that are accessible.

  • List projects a federated user can access: GET /OS-FEDERATION/projects
  • List domains a federated user can access: GET /OS-FEDERATION/domains

More information on listing resources can be found here.

Example cURL

$ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/projects

or

$ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/domains

Get a scoped token

A federated user may request a scoped token, by using the unscoped token. A project or domain may be specified by either id or name. An id is sufficient to uniquely identify a project or domain.

More information on getting a scoped token can be found here.

Example cURL

$ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["saml2"],"saml2":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "Default"},"name":"service"}}}}' -D - http://localhost:5000/v3/auth/tokens