This patch updates and adds examples and clarifies some instructions that were unclear or needed additional explanation for the Federation configuration overview, the Shibboleth setup instructions, and the horizon WebSSO documentation. These changes include: - Change instances of 'saml2' to 'mapped' where appropriate, since the documentation currently notes that using 'saml2' is deprecated - Make note of differences when using keystone-to-keystone federation and keystone as an Identity Provider where appropriate - Linkify section contents listings - Add examples using openstackclient - The examples include adding both a domain and a project for federated users, since there seems to be a horizon bug that cause federated users to not be able to log in if their group is only authorized on a domain and no projects[1] (not yet filed) - Move discussion of remote IDs from the websso section to the main configuration section, since the instructions to add identity providers are already in the main section and this is really more about keystone configuration than horizon configuration - Add example mapping rules for both a keystone-to-keystone configuration and a Shibboleth (using testshib.org) configuration - Correct description of token response format in "Performing federated authentication" section - Enhance description of configuration options for keystone as an IdP - Make the names and domain names of Service Providers and Identity Providers consistent throughout the documentation (beta and BETA were especially confusing) - Change references to wsgi-keystone.conf to keystone.conf since that's what devstack calls it now - Change keystone-to-keystone authentication demo to use keystoneauth instead of cURL (inspired by rodrigods's blog post on keystone-to-keystone[2]) - Move the note about fetching the SP's metadata to after shibboleth2.xml configuration is done, since the entityID needs to be set in the metadata for the IdP to recognize it - Enhance the description of what needs to be changed in shibboleth2.xml and use the package-generated example - Remove the section on removing REMOTE_USER from shibboleth2.xml, as this is needed to allow keystone to look up the remote user in the SAML assertion - Remove sections about keystone v3 from the WebSSO, that's old news and it's the default now - Add a step to ensure the SSO redirect template is copied into place, since devstack does not do that by default [1] http://git.openstack.org/cgit/openstack/django_openstack_auth/tree/openstack_auth/backend.py?h=2.4.1#n174 [2] http://blog.rodrigods.com/it-is-time-to-play-with-keystone-to-keystone-federation-in-kilo/ Change-Id: Id3ad18c43ace9e43d05b0acf966e577c909fa3e8
19 KiB
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.
Keystone as a Service Provider (SP)
Note
This feature is considered stable and supported as of the Juno release.
Prerequisites
This approach to federation supports keystone as a Service Provider, consuming identity properties issued by an external Identity Provider, such as SAML assertions or OpenID Connect claims, or by using Keystone as an Identity Provider (IdP).
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 identity properties. Keystone maps these values to keystone user groups and assignments created in keystone.
The following configuration steps were performed on a machine running Ubuntu 14.04 and Apache 2.4.7.
To enable federation, you'll need to:
- Run keystone under Apache, rather than using uwsgi command.
- Configure Apache to use a federation capable authentication method.
- Configure Federation in Keystone.
Configure Apache to use a federation capable authentication method
There is currently support for two major federation protocols:
- SAML - Keystone supports the following implementations:
- Shibboleth - see Setup Shibboleth.
- Mellon - see Setup Mellon.
- OpenID Connect - see Setup OpenID Connect.
Configure keystone and Horizon for Single Sign-On
- To configure horizon to access a federated keystone, follow the steps outlined at: Keystone Federation and Horizon.
Configure Federation in Keystone
Now that the Identity Provider and keystone are communicating we can
start to configure federation
.
- Configure authentication drivers in keystone.conf
- Create keystone groups and assign roles
- Add Identity Provider(s), Mapping(s), and Protocol(s)
Configure authentication drivers in keystone.conf
Note
saml2
has been deprecated as of the Mitaka release.
Support for the saml2
wrapper will be removed as of the "O"
release. The recommended authentication method is mapped
,
which supports saml2
.
Add the authentication methods to the [auth]
section in
keystone.conf
. Names should be equal to protocol names
added via Identity API v3. Here we use examples mapped
and
openid
.
[auth]
methods = external,password,token,mapped,openid
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.
For example, create a new domain and project like this:
$ openstack domain create federated_domain
$ openstack project create federated_project --domain federated_domain
And a new group like this:
$ openstack group create federated_users
Add the group to the domain and project:
$ openstack role add --group federated_users --domain federated_domain Member
$ openstack role add --group federated_users --project federated_project Member
We'll later add a mapping that makes all federated users a part of this group and therefore members of the new domain.
Add Identity Provider(s), Mapping(s), and Protocol(s)
To utilize federation the following must be created in the Identity Service:
Read more about federation in keystone.
Identity Provider
Create an Identity Provider object in keystone, which represents the Identity Provider we will use to authenticate end users:
$ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp
The value for the remote-id
option is the Entity ID
provided by the IdP. It is the same value that you set for the SSO
entityID in /etc/shibboleth/shibboleth2.xml. If the IdP is a Keystone
IdP, it is the value set in that Keystone's
[saml]/idp_entity_id
option. It will usually appear as a
URI but there is no requirement for it to resolve to anything and may be
arbitrarily decided by the administrator of the IdP. The local name,
here called 'myidp', is decided by you and will be used by the mapping
and protocol, and later for authentication.
A keystone identity provider may have multiple remote_ids specified, this allows the same
keystone identity provider resource to be used with multiple
external identity providers. For example, an identity provider resource
university-idp
, may have the following `remote_ids`:
['university-x', 'university-y', 'university-z']
. This
removes the need to configure N identity providers in keystone.
Note
Remote IDs are globally unique. Two identity providers cannot be associated with the same remote ID. Once authenticated with the external identity provider, keystone will determine which identity provider and mapping to use based on the protocol and the value returned from the remote_id_attribute key.
For example, if our identity provider is google
, the
mapping used is google_mapping
and the protocol is
oidc
. The identity provider's remote IDs would be:
[accounts.google.com
]. The remote_id_attribute value may be set to
HTTP_OIDC_ISS
, since this value will always be
accounts.google.com
.
The motivation for this approach is that there will always be some data sent by the identity provider (in the assertion or claim) that uniquely identifies the identity provider. This removes the requirement for horizon to list all the identity providers that are trusted by keystone.
Read more about identity providers.
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. There are many different ways to setup as well as
combine these rules. More information on rules can be found on the mapping_combinations
page.
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.
As a simple example, if keystone is your IdP, you can map a few known remote users to the group you already created:
$ cat > rules.json <<EOF
[
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "Default"
},
"name": "federated_users"
}
}
],
"remote": [
{
"type": "openstack_user",
"any_one_of": [
"demo",
"alt_demo"
]
}
]
}
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping
As another example, if Shibboleth is your IdP, the remote section should use REMOTE_USER as the remote type:
$ cat > rules.json <<EOF
[
{
"local": [
{
"user": {
"name": "{0}"
},
"group": {
"domain": {
"name": "Default"
},
"name": "federated_users"
}
}
],
"remote": [
{
"type": "REMOTE_USER"
}
]
}
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping
Read more about mapping.
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.
You can create a protocol like this:
$ openstack federation protocol create mapped --mapping myidp_mapping --identity-provider myidp
The name you give the protocol is not arbitrary. It must match the
method name you gave in the [auth]/methods
config option.
When authenticating it will be referred to as the
protocol_id
.
Read more about federation protocols
Performing federated authentication
Note
Authentication with keystone-to-keystone federation does not follow these steps. See Testing it all out to authenticate with keystone-to-keystone.
- Authenticate externally and generate an unscoped token in keystone
- Determine accessible resources
- 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/{idp_id}/protocols/{protocol_id}/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 JSON format, with the ID in the X-Subject-Token header.
In the returned unscoped token, a list of Identity Service groups the user belongs to will be included.
Read more about getting an unscoped token.
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/{idp_id}/protocols/{protocol_id}/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
Read more about listing resources.
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.
Read more about getting a scoped token.
Example cURL
$ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"mapped":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "federated_domain"},"name":"federated_project"}}}}' -D - http://localhost:5000/v3/auth/tokens
Keystone as an Identity Provider (IdP)
Note
This feature is experimental and unsupported in Juno (with several issues that will not be backported). These issues have been fixed and this feature is considered stable and supported as of the Kilo release.
Note
This feature requires installation of the xmlsec1 tool via your distribution packaging system (for instance apt or yum)
Example for apt:
$ apt-get install xmlsec1
Configuration Options
There are certain settings in keystone.conf
that must be
setup, prior to attempting to federate multiple keystone
deployments.
Within keystone.conf
, assign values to the
[saml]
related fields, for example:
[saml]
idp_entity_id=https://myidp.example.com/v3/OS-FEDERATION/saml2/idp
idp_sso_endpoint=https://myidp.example.com/v3/OS-FEDERATION/saml2/sso
idp_entity_id
is the unique identifier for the Identity
Provider. It usually takes the form of a URI but it does not have to
resolve to anything. idp_sso_endpoint
is required to
generate valid metadata but its value is not important, though it may be
in the future.
Note the certfile
, keyfile
, and
idp_metadata_path
settings and adjust them if
necessary:
certfile=/etc/keystone/ssl/certs/signing_cert.pem
keyfile=/etc/keystone/ssl/private/signing_key.pem
idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
Though not necessary, the follow Organization configuration options should also be setup. It is recommended that these values be URL safe.
idp_organization_name=example_company
idp_organization_display_name=Example Corp.
idp_organization_url=example.com
As with the Organization options, the Contact options, are not necessary, but it's advisable to set these values too.
idp_contact_company=example_company
idp_contact_name=John
idp_contact_surname=Smith
idp_contact_email=jsmith@example.com
idp_contact_telephone=555-555-5555
idp_contact_type=technical
Generate Metadata
In order to create a trust between the IdP and SP, metadata must be exchanged.
First, if you haven't already generated a PKI key pair, you need to
do so and copy those files the locations designated by
certfile
and keyfile
options that were
assigned in the previous section. Ensure that your apache vhost has SSL
enabled and is using that keypair by adding the following to the
vhost:
SSLEngine on
SSLCertificateFile /etc/keystone/ssl/certs/signing_cert.pem
SSLCertificateKeyFile /etc/keystone/ssl/private/signing_key.pem
To create metadata for your keystone IdP, run the
keystone-manage
command and redirect the output to a file.
For example:
$ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
Note
The file location should match the value of the configuration option
idp_metadata_path
that was assigned in the previous
section.
Finally, restart apache.
Create a Service Provider (SP)
In this example we are creating a new Service Provider with an ID of
mysp
, a sp_url
of
http://mysp.example.com/Shibboleth.sso/SAML2/ECP
and a
auth_url
of
http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth
. The sp_url
will be used when creating a SAML assertion
for mysp
and signed by the current keystone IdP. The
auth_url
is used to retrieve the token for
mysp
once the SAML assertion is sent. The auth_url has the
format described in Get an unscoped
token.
$ openstack service provider create --service-provider-url 'http://mysp.example.com/Shibboleth.sso/SAML2/ECP' --auth-url http://mysp.example.com:5000/v3/OS-FEDERATION/identity_providers/myidp/protocols/mapped/auth mysp
Testing it all out
Use keystoneauth to create a password session with the IdP, then use the session to authenticate with the SP, and get a scoped token from the SP.
Note
ECP stands for Enhanced Client or Proxy, an extension from the SAML2 protocol used in non-browser interfaces, like in the following example.
import os
from keystoneauth1 import session
from keystoneauth1.identity import v3
from keystoneauth1.identity.v3 import k2k
= v3.Password(auth_url=os.environ.get('OS_AUTH_URL'),
auth =os.environ.get('OS_USERNAME'),
username=os.environ.get('OS_PASSWORD'),
password=os.environ.get('OS_USER_DOMAIN_NAME'),
user_domain_name=os.environ.get('OS_PROJECT_NAME'),
project_name=os.environ.get('OS_PROJECT_DOMAIN_NAME'))
project_domain_name= session.Session(auth=auth)
password_session = k2k.Keystone2Keystone(password_session.auth, 'mysp',
k2ksession ='federated_domain')
domain_name= k2ksession.get_auth_ref(password_session)
auth_ref = auth_ref.auth_token
scoped_token_id print('Scoped token id: %s' % scoped_token_id)