Keystone federation
With the Keystone federation access strategy, users authenticate to Keystone themselves through single sign-on instead of OSIE managing a Keystone service account for them. OSIE's realms are full OpenID Connect providers, so Keystone can federate directly to a realm — or, at scale, to a single broker realm fronting many customer realms.
This page covers the OpenStack-side configuration. The OSIE-side configuration (realms, identity providers, domain access) is done in the admin dashboard — see OpenStack domain access and Linking realms.
Overview
Keystone federation follows the standard OS-FEDERATION WebSSO flow:
- OSIE redirects the user's browser to Keystone's WebSSO endpoint for the configured identity provider and protocol.
- Keystone sends the user to the OIDC provider — an OSIE realm — where the sign-in completes silently against the user's existing OSIE session.
- Keystone consumes the resulting token, applies its attribute mapping, and returns an unscoped token to OSIE's callback endpoint.
- OSIE keeps that token for the user's session and scopes it to projects on demand. No user credentials are stored.
Prerequisites
- Keystone with
OS-FEDERATIONand an OIDC-capable authentication module enabled. - The OSIE realm's issuer and discovery URLs, shown on the realm's General tab in the admin dashboard
(for example
https://cloud.example.com/realms/acme). - An OAuth2 client for Keystone, created on that realm's OAuth2 clients tab. Use its client ID and secret in the OIDC module configuration of Keystone.
Trusted dashboard
Keystone posts the WebSSO result to OSIE's callback endpoint. Whitelist it in keystone.conf — one entry serves all
realms and clouds:
[federation]
trusted_dashboard = https://cloud.example.com/api-v1/callbacks/keystone/websso
Replace the host with your OSIE API host. The callback URL is also displayed when configuring OpenStack domain access in the admin dashboard.
One realm, one domain
For a single realm mapped to a fixed domain, register the realm as an identity provider in Keystone, then create a mapping that shadows its users into the domain:
openstack identity provider create --remote-id https://cloud.example.com/realms/acme acme-idp
openstack mapping create --rules acme-mapping.json acme-mapping
openstack federation protocol create openid --identity-provider acme-idp --mapping acme-mapping
[
{
"local": [
{
"user": {
"name": "{0}",
"domain": { "name": "acme" }
}
}
],
"remote": [
{ "type": "OIDC-sub" }
]
}
]
In OSIE, map the realm to that domain with the Use Keystone token strategy and select the identity provider and protocol you just created.
Many realms, one identity provider — the broker realm
Registering an identity provider and mapping per customer does not scale, and most Keystone deployments only match one
remote-id per identity provider. The broker realm removes that limitation:
- In OSIE, create one realm (for example
keystone-broker) and add each customer realm to it as a Link another realm identity provider. The broker needs no users and no login page of its own. - In Keystone, register one identity provider and one mapping, pointing at the broker realm's issuer.
When a user signs in through the broker, the token OSIE issues to Keystone carries an os_domain_id claim — the ID of
the OpenStack domain mapped for the user's home realm. A dynamic mapping places each user in their own domain:
[
{
"local": [
{
"user": {
"name": "{0}",
"domain": { "id": "{1}" }
}
}
],
"remote": [
{ "type": "OIDC-sub" },
{ "type": "OIDC-os_domain_id" }
]
}
]
openstack identity provider create --remote-id https://cloud.example.com/realms/keystone-broker broker-idp
openstack mapping create --rules broker-mapping.json broker-mapping
openstack federation protocol create openid --identity-provider broker-idp --mapping broker-mapping
Note that the mapping reads the domain ID (domain.id), not the domain name — the claim carries the ID so the
mapping works without lookups.
Onboarding another customer then requires no Keystone changes: create the customer realm, link it into the broker realm, and add the realm's OpenStack domain access with the Use Keystone token strategy pointing at the broker's identity provider and protocol.
Requirements and caveats
- Consistent user identity — the mapping above keys shadow users on the token subject, which is stable per OSIE user. Keep the mapping's user naming stable over time; renaming rules creates new shadow users in Keystone.
- Project roles — OSIE continues to manage project role assignments for federated users through the cloud's admin credentials, so project membership granted in OSIE works the same as with auto-provisioned accounts.
- User-bound resources — switching an existing realm from auto-provision to Keystone federation changes which Keystone user each person is. Resources bound to the previous Keystone users (SSH key pairs, application credentials) do not carry over.