Rancher External Identity Providers: A Minimal SAML/OIDC Architecture for Multi-Cluster SSO

The problem this solves

If you run Rancher in front of several Kubernetes clusters, every local account you create in Rancher is a second source of truth for identity. People leave the company, passwords drift out of policy, and access reviews become archaeology. Rancher 2.x's built-in SAML 2.0 and OIDC support removes that duplication: one login flow, driven by your existing IdP (Okta, Entra ID, OneLogin, Keycloak), governs access to the Rancher UI and API for every managed cluster.

The useful takeaway: the design that works is smaller than most teams expect. You configure the IdP once in Rancher, map a groups claim to Rancher roles, and leave the downstream clusters' authentication completely alone.

Requirements

• Rancher 2.x (any recent 2.6/2.7/2.8 release; the UI layout differs slightly between minor versions, so check your release notes).
• An IdP that supports SAML 2.0 or OIDC and can expose a groups attribute/claim plus email and a stable subject identifier (NameID for SAML, sub for OIDC).
• For SAML: a valid X.509 signing certificate from the IdP, and a plan for rotating it before expiry.
• Admin access to Rancher (a local admin account) and app-admin access in the IdP to register Rancher as a service provider / client.
• HTTPS on the Rancher endpoint. The assertion consumer service (ACS) URL must match what the IdP has registered, including scheme and hostname.

The smallest suitable design

Pick one protocol and one provider. OIDC is the simpler choice when your IdP supports it — no certificate exchange, claims arrive as JSON — but SAML is fine and often mandatory in older enterprise environments. Do not enable both for the same user population unless you have a migration reason.

The design has three parts:

1. Register Rancher at the IdP. Create an application with the Rancher ACS URL (SAML) or redirect URI (OIDC), typically https://<rancher-host>/v1-saml/<provider>/saml/acs or the OIDC equivalent shown in the Rancher UI. Configure it to send email and groups.
2. Configure the provider in Rancher. In the Rancher UI go to Users & Authentication → Auth Provider (in older versions, Authentication → Identity Providers). Supply the IdP metadata URL or upload the metadata file, paste the signing certificate for SAML, and fill in the attribute mapping fields: which attribute carries the user's name, email, and groups.
3. Map groups to roles, not users. Assign Rancher global roles, cluster roles, or project roles to IdP groups. Individual user assignments become unnecessary; new users are provisioned in Rancher automatically on first login and inherit whatever their groups grant.

Keep exactly one local admin account as a break-glass login, with its password stored in your vault. If the IdP has an outage or someone misconfigures the group claim, that account is how you get back in.

Trust and data boundaries

Two boundaries matter here, and the design respects both:

Rancher to managed clusters. Downstream clusters are untouched by this change. They continue to trust Rancher as their authentication proxy; the IdP assertion never reaches them directly. This preserves cluster isolation — a cluster can be detached or imported elsewhere without reworking its auth.

Rancher to the IdP. Rancher stores the IdP configuration (metadata, certificates, mapping rules) in the management cluster's etcd. That makes etcd a trust anchor: anyone who can write to it can substitute IdP metadata and mint access. Restrict etcd snapshot and API access accordingly, and include the identity provider config in your etcd backup/restore tests.

Operational checks

After enabling the provider, verify in this order:

1. In the Auth Provider page, confirm the provider shows as enabled with the correct metadata URL and ACS endpoint.
2. Log out, start a fresh login, and confirm you are redirected to the IdP and returned to Rancher after authenticating. Test with a non-admin user, not just your admin account.
3. Open Users and confirm the test user was provisioned and that their IdP groups appear and map to the expected roles.
4. Check the audit log for the authentication events — successful and at least one deliberately failed attempt — so you know failure logging works before you need it.
5. Optionally confirm persistence on the management cluster with etcdctl (requires etcd client certs and direct etcd access; read-only, low risk): etcdctl get /config/identity_providers --prefix should show the stored configuration matching the UI.

For the negative test, temporarily remove the test user from the IdP group and confirm access is revoked on next login rather than cached indefinitely.

Failure modes

• Expired SAML signing certificate. The classic outage: every login fails at once. Track the IdP certificate expiry like any other TLS asset and rotate before it lapses.
• Missing or renamed groups claim. Users authenticate successfully but land with no roles. Symptom: "logged in but can't see any clusters." Fix the claim at the IdP or adjust the attribute mapping; check what claim names the IdP actually sends before assuming standard names.
• ACS/redirect URL mismatch. Happens after a hostname or TLS termination change. The IdP rejects the response. Keep the registered URL and the actual Rancher server URL in sync.
• IdP unavailability. No one can log in via SSO. This is what the break-glass local admin is for.
• etcd compromise or bad restore. Tampered or stale IdP metadata. Mitigate with tight etcd access controls and tested restores.

When this design changes

Revisit the single-provider design if you acquire a second organization with its own IdP (Rancher supports only one external provider as the primary auth source at a time in most versions — verify against your release), if you need machine-to-machine access (use service accounts and API tokens instead; SSO is for humans), or if you outgrow group-to-role mapping granularity and need per-cluster exceptions that justify a dedicated authorization layer. Until one of those is true, one provider, group-based roles, and a guarded local admin is the whole architecture.