🔐 Setting Up Keystone Federation in OpenStack

Local Keystone accounts don’t scale as an identity strategy. The moment your company has an SSO provider — Okta, Azure AD, Keycloak, your own Active Directory — the question becomes “why does OpenStack have its own separate username and password?” The answer is it shouldn’t. Keystone federation lets users authenticate against your existing identity provider and never have a local OpenStack credential at all.

I’ve set up federation against several IdPs in production, and it’s genuinely powerful — but the mapping rules are where everyone gets stuck. Here’s the working operator’s guide.

The two federation flavors

Keystone federates two ways:

• SAML 2.0 via mod_auth_mellon or Shibboleth — the enterprise standard, common with ADFS and older IdPs.
• OpenID Connect via mod_auth_openidc — cleaner, JSON-based, what I’d choose today against Keycloak, Okta, or Azure AD.

Either way the architecture is the same: Keystone runs behind Apache, the auth module handles the IdP handshake, and Keystone consumes the resulting assertion. The pieces you configure in Keystone are an identity provider, a protocol, and a mapping. The mapping is the hard part.

Registering the IdP and protocol

After the Apache module is talking to your IdP, register it in Keystone:

# Register the external IdP
openstack identity provider create company-idp \
  --remote-id https://idp.company.com/realms/main

# Create the mapping (defined below) then bind a protocol to the IdP
openstack mapping create company-mapping --rules /etc/keystone/mapping.json

openstack federation protocol create openid \
  --identity-provider company-idp \
  --mapping company-mapping

The --remote-id must exactly match the issuer the IdP advertises — a trailing-slash mismatch here is the cause of half the “federated login fails silently” tickets.

The mapping is where the work is

A mapping translates IdP assertions (groups, email, roles) into OpenStack identity (which Keystone groups/projects the user gets). This is the piece you’ll iterate on. A typical OIDC mapping:

[
  {
    "local": [
      {
        "user": { "name": "{0}" },
        "groups": "{1}",
        "domain": { "name": "Federated" }
      }
    ],
    "remote": [
      { "type": "OIDC-preferred_username" },
      { "type": "OIDC-groups" }
    ]
  }
]

This says: take the IdP’s preferred_username as the OpenStack username and map the IdP’s groups claim onto Keystone groups (which must already exist and be assigned roles on projects). The remote block matches assertion attributes; the local block constructs the OpenStack identity. The {0}, {1} positionally reference the matched remote attributes.

The crucial design decision: users get authorization through group-to-project role assignments, not individual grants. You pre-create Keystone groups, assign them roles on projects, and the mapping just routes federated users into the right groups based on their IdP claims. Add a user to the platform-admins group in your IdP and they get admin in OpenStack — no Keystone change needed.

Restricting who gets in

A naive mapping lets anyone your IdP authenticates into OpenStack. Use mapping rules with whitelist/blacklist or conditions to gate on a specific group claim:

{
  "remote": [
    { "type": "OIDC-groups", "any_one_of": ["openstack-users"] }
  ]
}

Now only IdP users in the openstack-users group can federate in. I always add this — federation without an entry gate is an accidental “the whole company is now in OpenStack” event.

Testing the flow

Federated auth uses a different token flow. Test it explicitly:

# Get a federated unscoped token, then list what projects you can scope to
openstack --os-auth-type v3oidcpassword \
  --os-identity-provider company-idp \
  --os-protocol openid \
  --os-discovery-endpoint https://idp.company.com/.well-known/openid-configuration \
  --os-client-id openstack \
  --os-client-secret <secret> \
  token issue

The web flow (Horizon SSO button) is what users see, but the CLI flow above is how I debug, because it surfaces the actual error instead of a generic Horizon redirect loop.

The failures I keep hitting

• Empty groups after login. The mapping matched the user but the groups claim didn’t come through, so they authenticate but can scope to nothing. Check the IdP is actually releasing the groups claim and the claim name matches your remote type exactly.
• remote-id mismatch. Login bounces back with no error. Almost always the issuer string doesn’t match --remote-id.
• Clock skew. SAML/OIDC assertions are time-bound. NTP drift between Keystone and the IdP causes intermittent, maddening auth failures. Keep both on tight NTP.

I keep an AI prompt that takes a mapping JSON plus a sample assertion (claims redacted) and tells me why a user landed in no groups — it catches claim-name mismatches faster than I can diff them. A few of these live in our prompt library.

Should you federate?

My rule: federate as soon as you have a corporate IdP and more than a handful of users. The payoff is huge — no local password sprawl, instant deprovisioning when someone leaves the company, MFA inherited from your IdP for free. Keep a couple of local Keystone admin accounts as a break-glass path for when the IdP itself is down, but route everyone else through federation.

Where to go next

Keystone federation turns OpenStack identity from a second set of credentials into a clean extension of your existing SSO. The setup is Apache plus an IdP plus a protocol; the real work is the mapping and the group-to-role design behind it. Gate entry with a group claim, keep a break-glass local admin, and watch your clocks. For the rest of the Keystone and identity story, see the OpenStack category.

Federation changes who can access your entire cloud. Validate mapping rules and entry restrictions in a non-production Keystone before pointing real users at it.