How authentik signs Rancher users in over OIDC
authentik's Rancher guide, marked with authentik support level in the integrations catalog, configures an OAuth2/OpenID provider for Rancher, and Rancher's generic OIDC auth provider is the piece that consumes it. For a platform team that wants one identity source for Rancher access, the integration means a user signs in with their authentik account, and Rancher reads the claims in the token to decide who that person is inside Rancher. Nothing about the sign-in itself requires Rancher to hold passwords or a separate user directory for these people. The integration stops at the Rancher layer. It decides who can enter Rancher and which global and cluster roles Rancher assigns, but it does not replace Kubernetes RBAC on the clusters themselves. Rancher turns its own role assignments into Kubernetes permissions, so a mistake in the group mapping can grant more reach than intended, and the cluster-level bindings still need review. Treat the OIDC setup as the front door and Kubernetes authorization as the rooms behind it, and confirm in your Rancher version how global and cluster roles map to what the clusters enforce.
Three decisions come before any setting is changed. First, group design: decide which authentik groups correspond to Rancher global roles and which to cluster or project roles, and keep that list short enough that someone can audit it. Second, role mapping: confirm which group claim name your authentik provider emits and how Rancher's OIDC settings read it, because an empty or misnamed claim usually produces users who sign in with no access. Third, the recovery path: keep the local admin account enabled and its credentials stored outside the SSO flow, so that a misconfigured provider or an authentik outage does not lock every administrator out. Test the recovery login before you enforce SSO for everyone.
What you need before you configure authentik and Rancher
Five things must be in place before you touch the Rancher auth settings: a supported authentik release, a Rancher version confirmed against the integration guide, public HTTPS names for both systems, trusted certificates between them, and an authentik group structure that matches the Rancher roles you plan to grant. Each check below proves one of these is ready, so a failure shows up before you change the login path for your users.
Supported authentik release
Confirm the authentik version you run appears in the security policy as a supported line that receives security fixes. Compare your running version against the release list, and plan an upgrade if it has fallen out of support. Check the release notes for the version you intend to run, because breaking changes can affect OIDC provider settings. Record the version so you can match it to the Rancher guide later.
Confirmed Rancher version
Check your Rancher version against the authentik Rancher integration guide before you copy any client settings. The guide is marked with authentik support level, so confirm the exact steps it describes match the Rancher release you run. Note the Rancher version in your change record, because auth provider screens and required fields can differ between releases.
Public HTTPS names for both systems
Give Rancher and authentik stable public HTTPS hostnames with valid certificates. The OIDC redirect URI and the issuer URL are built from these names, so a hostname change later breaks sign-in. Verify that each name resolves from the networks your users and the Rancher server use, and that the authentik issuer endpoint answers over HTTPS with no redirect loop.
Certificate trust between Rancher and authentik
Rancher must be able to reach the authentik OIDC discovery and token endpoints and trust the certificate chain behind them. If authentik uses an internal certificate authority, install that CA in the Rancher environment before configuration. Test with a request from the Rancher host itself, not from your workstation, because the workstation may trust a CA the server does not.
Authentik groups matching Rancher roles
Decide which Rancher global and cluster roles you will grant, then create the matching authentik groups before configuration. Rancher reads group claims from the token, so a group that does not exist in authentik cannot grant access. Map each group to one role in a short table, assign a test user to each group, and confirm the group name appears in the token claim with the exact spelling you will use in Rancher.
Configure the authentik OAuth2 provider and Rancher auth provider
This sequence creates the authentik OAuth2/OIDC provider, scopes the groups that carry Rancher roles, and enables Rancher's generic OIDC auth provider with matching values, so that a non-admin user can sign in and Rancher receives the group claims it needs.
Confirm the Rancher redirect URI and callback
Before creating anything in authentik, record the exact callback URL your Rancher server expects for its generic OIDC provider, using the server URL you plan to publish and the path Rancher's documentation gives for the OIDC login callback. Check the authentik Rancher guide in the integrations catalog for the current path, because the redirect URI must match byte for byte. Ask the Rancher administrator to confirm the public hostname and TLS certificate chain that browsers will use. This step is done when you have one written redirect URI and one written Rancher server URL that both teams agree on.
Create the OAuth2/OIDC provider in authentik
In the authentik admin interface, create an OAuth2/OpenID provider for Rancher and an application that points to it. Set the client type to confidential so that Rancher can hold the client secret, enter the redirect URI from the previous step, and choose the signing key and scopes that include the profile, email and groups claims. Bind the application to an authorization flow your users already pass through. This step is done when the provider and application are saved and visible in the admin interface.
Record the client ID, secret and discovery URL
Copy the client ID and client secret from the provider page and store them in your secrets manager, not in a shared document or chat. Note the OpenID configuration discovery URL that authentik shows for the provider, which normally ends in the application slug and the well-known configuration path. Open that URL in a browser or with curl from a machine that can reach authentik, and confirm that the JSON document loads and lists an issuer, authorization endpoint, token endpoint and JWKS URI. This step is done when the discovery document loads without a certificate error.
Scope the groups that will carry Rancher roles
Decide which authentik groups map to Rancher global roles and cluster roles, for example one group for Rancher administrators and separate groups for each cluster's read-only or project users. Create those groups in authentik, add a test non-admin account to one of them, and confirm that the groups scope or property mapping included in the provider emits a groups claim with the group names. Keep the group names stable, because Rancher role assignments refer to them. This step is done when a token issued to the test account contains the expected group values.
Enable the generic OIDC auth provider in Rancher
In Rancher, open the authentication settings and enable the generic OIDC provider. Enter the issuer or discovery URL, the client ID, the client secret and the scopes that include groups, using the values recorded earlier. Set the group claim name to match the claim your authentik mapping emits, and set the access mode and allowed principals according to your policy. Save the configuration while keeping your existing local admin session open, so you can revert if the save fails. This step is done when Rancher accepts the configuration and shows the provider as enabled.
Test a login with a non-admin account
Sign out of Rancher, then sign in using a test account that belongs only to a non-administrator group. Confirm that the authentik consent and login screens appear, that Rancher returns you to the console, and that the user sees only the global and cluster roles assigned to that group. If the login fails, check the redirect URI, the client secret and the group claim name before changing role bindings. This step is done when the non-admin login succeeds and the permissions match the group.
Verify group claims against Rancher role bindings
Review the claims Rancher receives for the test user and compare them with the global role and cluster role bindings you configured. Confirm that a user in an administrator group receives the expected global role and that a user outside every mapped group is denied or receives no roles, depending on your access mode. Keep a documented local admin account with a stored password and a tested login path for recovery, and confirm it still works while OIDC is enabled. This step is done when role assignments match the group membership for at least one user per group and the recovery path is tested.
Mapping authentik groups to Rancher global and cluster roles
This table compares each authentik group with the Rancher scope it should reach, the role granted there, and who approves membership. The rows are illustrative only, so replace group names and roles with the ones your Rancher version and your access model define. Keep global and cluster grants as separate decisions, and treat a user in no mapped group as having no elevated access.
| authentik group (illustrative) | Rancher scope | Rancher role assigned | Who approves membership |
|---|---|---|---|
| rancher-platform-admins (illustrative) | Global | Global admin, confirm the exact role name in your Rancher version | Head of platform engineering, with a second approver from security |
| rancher-global-viewers (illustrative) | Global | Read-only global role, confirm the exact role name in your Rancher version | Platform team lead |
| rancher-prod-cluster-admins (illustrative) | Cluster (production cluster only) | Cluster owner role, confirm the exact role name in your Rancher version | Owner of the production cluster and change board |
| rancher-dev-cluster-editors (illustrative) | Cluster (development cluster only) | Cluster member role with edit rights, confirm the exact role name in your Rancher version | Application team lead for the workload |
| rancher-cluster-readonly (illustrative) | Cluster (named clusters) | Read-only cluster member role, confirm the exact role name in your Rancher version | Service owner who requests access |
| No mapped group | None | No Rancher role; the user sees no elevated access | Not applicable, access requires a group request |
Why the local admin account stays enabled for recovery
Keep a local Rancher admin enabled because the SSO path depends on authentik, the OIDC client secret, and the group claims being correct at the same moment. If any one of those fails, every user locked out of Rancher needs a way back in. The local account is that path. It is for recovery only, and it should be used when the authentik provider is unreachable, when a change to the groups claim or the client secret has broken login, or when the client secret has expired and must be rotated. Before go-live, confirm with your own change records which of these events your team will treat as triggers, and who is authorized to decide that SSO is down.
Protect the account as strictly as you protect the SSO path, because the local login bypasses authentik entirely. That means a long, unique password that no one reuses, stored in a sealed secret store such as OpenBao or your enterprise vault, with access limited to a named group and every retrieval logged. Confirm that the store's audit log reaches your central logging and that someone reviews those entries on a schedule. Rancher's own audit logging should also be turned on so that any action taken through the local account is traceable. Do not give the break-glass user a personal mailbox or a shared login that people use day to day, because that turns the account into a second everyday path.
Test the account on a schedule rather than leaving it in use. A simple cadence is to sign in with the local account in a non-production Rancher instance, confirm it still works, and rotate its password afterward, recording the result in your change system. In production, verify only that the account exists, is still disabled for routine use, and that its credentials can be retrieved by the on-call group. After any authentik upgrade, client secret rotation or claim change, repeat the check. Ask Rancher support or your deployment partner to confirm the exact steps for your Rancher version before you write the runbook, since the login and recovery screens differ between releases.
Hardening the authentik to Rancher trust path
The sign-in path from authentik to Rancher carries admin access to every cluster Rancher manages, so it needs the same controls as the clusters themselves. The cards below cover secrets, MFA, group scoping, admin limits, transport security and token lifetimes, and each one names a check your team can run before and after go-live.
Keep the client secret out of config
The OIDC client secret that authentik issues for Rancher should live in a secret store your team controls, not in Helm values, Rancher settings exported to files or shared runbooks. Anyone holding that secret can attempt to impersonate the Rancher client, so restrict who can read it in both authentik and your store. Record where it is injected and who can view it. Confirm that Rancher's own stored configuration does not expose the value to users who only need cluster access.
Rotate the client secret on a schedule
Set a defined rotation interval for the Rancher client secret and write it into your change calendar with an owner. Rotation touches both the authentik provider and the Rancher auth configuration, so plan a short window where both sides are updated and tested. Rehearse the rotation in a non-production Rancher first. Keep the previous secret valid only as long as the change window needs, then revoke it in authentik.
Require MFA on the Rancher application
Enforce a second factor in the authentik flow bound to the Rancher application, so that a password alone cannot start an OIDC login. Because Rancher delegates authentication, a weak authentik flow becomes a weak Rancher login. Check that the flow applies to every route into Rancher, including local login attempts that might bypass the provider. Test enrollment and recovery paths so that users who lose a factor do not receive a shortcut around MFA.
Restrict access by authentik group
Bind the Rancher application in authentik to a policy that admits only the groups that need Rancher at all. Users outside those groups should be refused at the authentik side, not just given no role after login. Review the binding whenever teams change and confirm that nested or inherited group membership does not widen access unintentionally. A user who authenticates but holds no Rancher role should still be a finding to investigate.
Limit global admin to a named group
Map only a small, named authentik group to the Rancher global admin role, and keep that group's membership reviewed on a fixed cadence. Use cluster and project roles for everyone else so that a compromised ordinary account cannot reach every cluster. Document who approves additions to the admin group and how removals take effect. Ask Rancher how it applies role changes to existing sessions, because a removed admin may keep access until the token expires.
Keep Rancher and the API on TLS
Serve the Rancher UI and the Kubernetes API that Rancher exposes over TLS with certificates your team issues and renews, and make sure the authentik redirect and issuer URLs use the same trusted chain. Check that the CA bundle configured for OIDC discovery is current, since a stale bundle breaks sign-in during renewal. Confirm which certificate authority signs the Kubernetes API endpoint for clients using OIDC tokens.
Check token lifetime and revocation
The Kubernetes authentication model accepts OpenID Connect tokens, so a token issued by authentik can continue to authenticate against the API until it expires, even after a user is disabled. Confirm the access token lifetime configured in authentik and how long Rancher caches sessions. Test revocation by disabling a test user and attempting API calls with a token obtained earlier. Document the exposure window you accept and the steps to shorten it during an incident.
How to test the integration before users depend on it
Test the Rancher and authentik integration with a fixed set of accounts before any production user signs in through it. Create one test user in each group you mapped to a Rancher global role or cluster role, one test user in no mapped group, and one test user that you have disabled in authentik. For each account, record the login result, the groups Rancher displays for the user, the global permissions and cluster roles Rancher actually grants, and whether the user is refused access to projects, namespaces or clusters outside that role. The disabled account matters most: confirm that Rancher refuses it, and check whether an already-issued Rancher session stays active after the account is disabled. Run the same matrix against each Rancher and authentik version you intend to operate, and confirm those exact versions in your test record, since group claim names and login behavior can change between releases.
Add three checks that are easy to skip. First, log out of Rancher and confirm the session ends, then sign in again and confirm group changes made in authentik since the last login are reflected. Second, let a session expire or force a token refresh and confirm the user keeps the same permissions, not a wider set. Third, sign in with the local admin account you kept for recovery and confirm it still works while the OIDC provider is enabled, because a broken provider configuration can lock out everyone at once. Test the local admin path from a separate browser session so an existing login does not mask a failure.
Write the results into a short test record that the change board can review: date, Rancher version, authentik version, the account list with group memberships, each expected and observed result, and the name of the person who ran the test. Any mismatch between expected and observed permissions blocks the rollout until it is explained or fixed. Keep the record with the change request so that a later permission question can be traced back to the tested configuration. Ask your Rancher support path and your authentik documentation which settings are safe to change after go-live, so the retest scope is clear for future changes.
Why Rancher logins fail after OIDC is enabled
This table pairs each common failed sign-in symptom with its likely cause and the check that confirms it. Work down the rows in order, because the first few causes block every login while the later ones affect only some users. Confirm the claims returned at login before changing any Rancher mapping.
| Symptom | Likely cause | Fix and confirming check |
|---|---|---|
| Redirect fails with an invalid redirect URI error at authentik | The redirect URI registered on the authentik OAuth2/OIDC provider does not exactly match the Rancher callback URL, including scheme, host and path. | Copy the callback URL shown in Rancher's auth provider settings into the provider's redirect URIs. Confirm by retrying login and checking the authentik event log for the rejected URI. |
| Rancher shows an error when saving the provider or on the login page | The issuer or discovery URL is not reachable from the Rancher pods or nodes, often because it resolves to an internal name or is blocked by egress rules. | Test the OpenID configuration URL from inside a Rancher pod or node with curl. Fix DNS or egress rules, then confirm Rancher can fetch the discovery document. |
| TLS or certificate errors during the callback or token exchange | authentik is served with a certificate issued by a private or internal CA that Rancher does not trust, or the chain is incomplete. | Add the CA certificate to Rancher's trusted certificate configuration and verify the full chain with openssl from the Rancher side. Confirm by repeating the login and checking Rancher logs for x509 errors. |
| User signs in but Rancher reports no global or cluster role | The group claim is missing from the token, or the group name differs from the value in the Rancher group mapping (case, prefix or full path). | Read the claims returned at login, for example in the authentik provider's preview or a test token, and compare the group values with the Rancher mapping. Adjust the mapping or the authentik group name, then test with a user who holds the group. |
| Users in the correct authentik group still get no role | The groups scope was not requested by Rancher, so authentik does not include the groups claim in the token even though the user is a member. | Add the groups scope to the Rancher OIDC settings and confirm the scope is included in the provider's scope mappings in authentik. Check the claims at login to confirm groups now appear. |
| Existing users are locked out or lose access after group changes | Rancher stores role assignments from the last successful login, and removing a user from an authentik group does not revoke Rancher access until the next sign-in or sync behavior is applied. | Review which roles are set directly in Rancher versus through group mapping. Confirm by removing a test user from the group, signing in again and checking their effective roles. Keep a local admin account to recover access if mappings are wrong. |
What buyers ask about authentik and Rancher SSO
Is the authentik Rancher integration supported by authentik?
Yes, authentik's integrations catalog marks its Rancher guide with the authentik support level, which means the guide configures an OAuth2/OpenID provider for Rancher and is covered by authentik's own integration documentation. Read the guide itself to confirm the Rancher version it targets, because the catalog label describes the integration, not every Rancher release. Support from authentik does not extend to your Rancher, Kubernetes or network configuration, so plan who owns troubleshooting for each layer before go-live. Our work covers planning and configuring the integration in your environment, and it does not change the vendor's support terms.
What drives the cost of a Rancher SSO integration?
Cost follows the written scope, so the main drivers are the number of clusters, how many group-to-role mappings you need, and how much certificate work the environment requires. Group design is often the largest factor: a flat model with a few global roles takes less effort than separate cluster and project roles per team. Certificate handling for the Rancher and authentik endpoints, the testing scope across clusters and user populations, and whether authentik itself must be deployed or upgraded first also change the quote. Recurring costs are mainly support or upgrade retainers, while the integration build is one-time. Ask for the quote to list each cluster, each role mapping and each test case separately.
How long does the Rancher SSO work take?
Duration depends on the same factors as cost: the number of clusters, the complexity of the group model, the state of your authentik deployment, and how many test cycles your change process requires. An authentik instance that is already running, reachable over HTTPS, and has the groups defined will shorten the work considerably. Certificate issues, approval steps for client registration, and any need to align Rancher and Kubernetes versions with your upgrade calendar can extend it. We agree a timeline in the written scope, so ask for the milestones and which items depend on your staff or change windows.
Can our own team set up authentik SSO for Rancher without a partner?
Yes, a team with working knowledge of authentik, Rancher and OIDC can build this integration in-house, since the authentik guide walks through the provider setup and Rancher's generic OIDC auth provider is configured in the Rancher UI. The effort is in the decisions: group claims must map cleanly to global and cluster roles, redirect URIs must match your Rancher hostname, and the local admin must remain usable for recovery. Teams without recent authentik or Kubernetes RBAC experience usually find the role model is where time goes. A partner is useful when you want the design reviewed, the testing scripted, and the change documented for auditors.
What does the integration need from our identity and platform staff?
Identity staff need to define the groups in authentik that will carry Rancher access, confirm which claims are included in tokens, and agree who approves group membership. Platform staff need to supply the Rancher hostname, the TLS certificate chain for both Rancher and authentik, and the list of clusters and projects that need role mappings. Both teams should agree on who administers the OAuth client secret and how it rotates. Plan a test group and test accounts so access changes can be verified before production users are moved. Ask us to write these inputs into the scope so nothing is discovered during the build.
How do we keep a local admin for recovery if SSO fails?
Keep the local Rancher admin account enabled and store its credentials in a sealed location that only named administrators can reach, with the access procedure documented. Test the recovery path before go-live by confirming that the local login works while the authentik provider is disabled in a non-production environment. Be aware that a misconfigured group mapping can lock out all SSO users, so the local admin is the path to fix the provider. Document who may use it, how the use is logged, and when credentials are rotated. Kubernetes authenticates users through OpenID Connect, so the cluster's own access controls should be reviewed alongside the Rancher login.
What should we check in the Rancher and authentik setup after go-live?
Check that group claims arrive in tokens as expected, that global roles and cluster roles match the design for a sample of users, and that removing a user from an authentik group removes their access. Confirm the redirect URIs, the client secret rotation date and the certificate expiry dates are recorded in your operations calendar. Review the authentik release line you run, since authentik's security policy lists supported versions and announces security releases at least 24 hours in advance. Re-test after Rancher or Kubernetes upgrades, because version changes can alter how tokens and roles are handled.
How DeployOpen scopes and delivers the Rancher SSO integration
DeployOpen plans, implements and documents self-hosted open-source platforms inside your own infrastructure. For authentik and Rancher SSO, we scope the OIDC provider, group claim mapping and recovery path in writing before any configuration starts, then hand over a tested setup your team can run.
How we scope
- Confirm your Rancher version, Rancher deployment model and the authentik version you run before agreeing the work.
- Agree which groups map to global roles, which map to cluster and project roles, and who approves each mapping.
- Record the local admin recovery procedure and the users allowed to use it in the written scope.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work begins.
How we build
- Create the generic OIDC auth provider in authentik with the Rancher redirect URI and the client settings for your environment.
- Configure the Rancher auth provider, group claim handling and role templates to match the agreed group design.
- Test sign-in with users from each group, confirming that global and cluster roles resolve as specified.
- Verify that the local admin login still works while SSO is enabled, and that a failed SSO login does not lock out operators.
How we hand over
- Deliver a written configuration record covering client settings, claim mappings, role assignments and secret locations.
- Document the break-glass procedure for the local admin, including where credentials are stored and who can retrieve them.
- Walk your platform team through group changes, client secret rotation and how to test a new user before granting access.
- Provide a test checklist your team can rerun after Rancher or authentik upgrades.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainer work can cover re-testing SSO after Rancher or authentik version changes and reviewing group mappings as teams change.
- Ask for a clear list of which upgrade checks are included in any retainer before you sign.
