Configuring Keystone for Federation¶

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:

1. Run keystone under Apache for SUSE, RedHat or Ubuntu, rather than using uwsgi command.
2. Configure Apache to use a federation capable authentication method.
3. Configure Federation in Keystone.

Configure Federation in Keystone¶

Now that the Identity Provider and keystone are communicating we can start to configure federation.

1. Configure authentication drivers in keystone.conf
2. Create keystone groups and assign roles
3. Add Identity Provider(s), Mapping(s), and Protocol(s)

[auth]
methods = external,password,token,saml2,openid

$ openstack domain create federated_domain
$ openstack project create federated_project --domain federated_domain

$ openstack group create federated_users

$ openstack role add --group federated_users --domain federated_domain Member
$ openstack role add --group federated_users --project federated_project Member

$ openstack identity provider create --remote-id https://myidp.example.com/v3/OS-FEDERATION/saml2/idp myidp

$ cat > rules.json <<EOF
[
    {
        "local": [
            {
                "user": {
                    "name": "{0}"
                },
                "group": {
                    "domain": {
                        "name": "Default"
                    },
                    "name": "federated_users"
                }
            }
        ],
        "remote": [
            {
                "type": "openstack_user"
            },
            {
                "type": "openstack_user",
                "any_one_of": [
                    "demo",
                    "alt_demo"
                ]
            }
        ]
    }
]
EOF
$ openstack mapping create --rules rules.json myidp_mapping

$ 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

$ openstack federation protocol create saml2 --mapping myidp_mapping --identity-provider myidp

Performing federated authentication¶

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

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

$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=http://localhost:5000/v3
$ openstack federation project list

$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_URL=http://localhost:5000/v3
$ openstack federation domain list

$ export OS_AUTH_TYPE=token
$ export OS_IDENTITY_API_VERSION=3
$ export OS_TOKEN=<unscoped token>
$ export OS_AUTH_URL=http://localhost:5000/v3
$ export OS_PROJECT_DOMAIN_NAME=federated_domain
$ export OS_PROJECT_NAME=federated_project
$ openstack token issue

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

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/saml2/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/saml2/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.

import os

from keystoneauth1 import session
from keystoneauth1.identity import v3
from keystoneauth1.identity.v3 import k2k

auth = v3.Password(auth_url=os.environ.get('OS_AUTH_URL'),
                   username=os.environ.get('OS_USERNAME'),
                   password=os.environ.get('OS_PASSWORD'),
                   user_domain_name=os.environ.get('OS_USER_DOMAIN_NAME'),
                   project_name=os.environ.get('OS_PROJECT_NAME'),
                   project_domain_name=os.environ.get('OS_PROJECT_DOMAIN_NAME'))
password_session = session.Session(auth=auth)
k2ksession = k2k.Keystone2Keystone(password_session.auth, 'mysp',
                                   domain_name='federated_domain')
auth_ref = k2ksession.get_auth_ref(password_session)
scoped_token_id = auth_ref.auth_token
print('Scoped token id: %s' % scoped_token_id)