Federated Identity¶

Configuring federation in keystone¶

1. Configure authentication drivers in keystone.conf by adding the authentication methods to the [auth] section in keystone.conf. Ensure the names are the same as to the protocol names added via Identity API v3.

   For example:

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

   Note

   saml2 and openid are instances of the mapped plugin. These must match the name of the of the federation protocol created via the Identity API. The other names in the example are not related to federation.

2. Create local keystone groups and assign roles.

   Important

   The keystone requires group-based role assignments to authorize federated users. The federation mapping engine maps federated users into local user groups, which are the actors in keystone’s role assignments.

3. Create an IdP object in keystone. The object must represent the IdP you will use to authenticate end users:

   PUT /OS-FEDERATION/identity_providers/{idp_id}
   

   More configuration information for IdPs can be found Register an Identity Provider.

4. Add mapping rules:

   PUT /OS-FEDERATION/mappings/{mapping_id}
   

   More configuration information for mapping rules can be found Create a mapping.

   Note

   The only keystone API objects that support mapping are groups and users.

5. Add a protocol object and specify the mapping ID you want to use with the combination of the IdP and protocol:

   PUT /OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}
   

   More configuration information for protocols can be found Add a protocol and attribute mapping to an identity provider.

Performing federated authentication¶

1. Authenticate externally and generate an unscoped token in keystone:

   Note

   Unlike other authentication methods in keystone, 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 IdP’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.

   GET/POST /OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth
   

2. 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

   GET /OS-FEDERATION/projects
   

3. Get a scoped token. A federated user can request a scoped token using the unscoped token. A project or domain can be specified by either ID or name. An ID is sufficient to uniquely identify a project or domain.

   POST /auth/tokens
   

Configuring federation in keystone¶

There are certain settings in keystone.conf that must be set up, prior to attempting to federate multiple keystone deployments.

1. Within keystone.conf, assign values to the [saml] related fields, for example:

   [saml]
   certfile=/etc/keystone/ssl/certs/ca.pem
   keyfile=/etc/keystone/ssl/private/cakey.pem
   idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
   idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
   idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml
   

2. We recommend the following Organization configuration options. Ensure these values contain not special characters that may cause problems as part of a URL:

   idp_organization_name=example_company
   idp_organization_display_name=Example Corp.
   idp_organization_url=example.com
   

3. As with the Organization options, the Contact options are not necessary, but it is advisable to set these values:

   idp_contact_company=example_company
   idp_contact_name=John
   idp_contact_surname=Smith
   idp_contact_email=jsmith@example.com
   idp_contact_telephone=555-55-5555
   idp_contact_type=technical
   

Generate metadata¶

Metadata must be exchanged to create a trust between the IdP and the SP.

1. Create metadata for your keystone IdP, run the keystone-manage command and pipe the output to a file. For example:

   $ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml
   

   Note

   The file location must match the value of the idp_metadata_path configuration option assigned previously.

Create a SP¶

To setup keystone-as-a-Service-Provider properly, you will need to understand what protocols are supported by external IdPs. For example, keystone as an SP can allow identities to federate in from a ADFS IdP but it must be configured to understand the SAML v2.0 protocol. ADFS issues assertions using SAML v2.0. Some examples of federated protocols include:

• SAML v2.0
• OpenID Connect

The following instructions are an example of how you can configure keystone as an SP.

1. Create a new SP with an ID of BETA.

2. Create a sp_url of http://beta.example.com/Shibboleth.sso/SAML2/ECP.

3. Create a auth_url of http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth.

   Note

   Use the sp_url when creating a SAML assertion for BETA and signed by the current keystone IdP. Use the auth_url when retrieving the token for BETA once the SAML assertion is sent.

4. Set the enabled field to true. It is set to false by default.

5. Your output should reflect the following example:

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

Mapping creation¶

Mapping creation starts with the communication between the IdP and SP. The IdP usually provides a set of assertions that their users have in their assertion document. The SP will have to map those assertions to known groups and roles. For example:

Identity Provider 1:
  name: jsmith
  groups: hacker
  other: <assertion information>
The Service Provider may have 3 groups:
  Admin Group
  Developer Group
  User Group

The mapping created by the Service Provider might look like:
  Local:
  Group: Developer Group
Remote:
  Groups: hackers

The Developer Group may have a role assignment on the Developer Project. When jsmith authenticates against IdP 1, it presents that assertion to the SP.The SP maps the jsmith user to the Developer Group because the assertion says jsmith is a member of the hacker group.

Mapping examples¶

A bare bones mapping is sufficient if you would like all federated users to have the same authorization in the SP cloud. However, mapping is quite powerful and flexible. You can map different remote users into different user groups in keystone, limited only by the number of assertions your IdP makes about each user.

A mapping is composed of a list of rules, and each rule is further composed of a list of remote attributes and a list of local attributes. If a rule is matched, all of the local attributes are applied in the SP. For a rule to match, all of the remote attributes it defines must match.

In the base case, a federated user simply needs an assertion containing an email address to be identified in the SP cloud. To achieve that, only one rule is needed that requires the presence of one remote attribute:

{
    "rules": [
        {
            "remote": [
                {
                    "type": "Email"
                }
            ],
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                }
            ]
        }
    ]
}

However, that is not particularly useful as the federated user would receive no authorization. To rectify it, you can map all federated users with email addresses into a federated-users group in the default domain. All federated users will then be able to consume whatever role assignments that user group has already received in keystone:

{
    "rules": [
        {
            "remote": [
                {
                    "type": "Email"
                }
            ],
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                },
                {
                    "group": {
                        "domain": {
                            "id": "0cd5e9"
                        },
                        "name": "federated-users"
                    }
                }
            ]
        }
    ]
}

This example can be expanded by adding a second rule that conveys additional authorization to only a subset of federated users. Federated users with a title attribute that matches either Manager or Supervisor are granted the hypothetical observer role, which would allow them to perform any read-only API call in the cloud:

{
    "rules": [
        {
            "remote": [
                {
                    "type": "Email"
                },
            ],
            "local": [
                {
                    "user": {
                        "name": "{0}"
                    }
                },
                {
                    "group": {
                        "domain": {
                            "id": "default"
                        },
                        "name": "federated-users"
                    }
                }
            ]
        },
        {
            "remote": [
                {
                    "type": "Title",
                    "any_one_of": [".*Manager$", "Supervisor"],
                    "regex": "true"
                },
            ],
            "local": [
                {
                    "group": {
                        "domain": {
                            "id": "default"
                        },
                        "name": "observers"
                    }
                }
            ]
        }
    ]
}

Keystone also supports the following:

• not_any_of, matches any assertion that does not include one of the specified values
• blacklist, matches all assertions of the specified type except those included in the specified value
• whitelist does not match any assertion except those listed in the specified value.