Skip to content

Commit 413b76b

Browse files
dcharles525dcharles525
authored
Merge pull request #470 from epinio/docs/rancher-aligned-sso
docs: Rancher-aligned SSO guide and API reference updates
2 parents 4a4080a + 82e816f commit 413b76b

2 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎docs/howtos/operations/configuring_rancher_sso.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
sidebar_label: "Rancher as OIDC Provider"
3+
sidebar_position: 22
4+
title: "Using Rancher as an OIDC Provider for Epinio"
5+
description: How to configure Rancher Manager as an OIDC identity provider for Epinio via Dex.
6+
keywords: [epinio, kubernetes, rancher, sso, oidc, dex, identity]
7+
doc-type: [how-to]
8+
doc-topic: [epinio, customize, operations, rancher, sso]
9+
---
10+
11+
# Using Rancher as an OIDC Provider for Epinio
12+
13+
Rancher Manager (v2.12+) can act as an OpenID Connect (OIDC) identity provider. This guide walks through configuring Rancher as the OIDC issuer and connecting it to Epinio's Dex instance so that users authenticated in Rancher can sign in to Epinio with SSO.
14+
15+
## Prerequisites
16+
17+
- Rancher Manager with an external auth provider already configured (e.g., GitHub, Active Directory, SAML). Rancher's OIDC provider surfaces the identities from whatever upstream auth Rancher itself uses.
18+
- The `oidc-provider` feature flag enabled on Rancher. Enable it under **☰ → Global Settings → Feature Flags**, or via:
19+
```bash
20+
kubectl patch features oidc-provider -p '{"spec":{"value":true}}' --type merge
21+
```
22+
- Epinio installed with Dex enabled.
23+
- Access to the `dex-config` secret in the `epinio` namespace.
24+
25+
## Overview
26+
27+
The integration has two sides:
28+
29+
1. **Rancher side** — Register an OIDC client for Dex in Rancher. Rancher generates a client ID and secret. See [Configure Rancher as an OIDC Provider](https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/configure-oidc-provider).
30+
2. **Dex side** — Configure an OIDC connector in Dex that points at Rancher's OIDC issuer, using the credentials from step 1.
31+
32+
```
33+
User → Epinio UI → Dex → Rancher (OIDC) → Upstream IdP (e.g., GitHub)
34+
↑ ↓
35+
←──── id_token + claims ────┘
36+
```
37+
38+
## Step 1: Register Dex as an OIDC Client in Rancher
39+
40+
Follow the Rancher documentation to create an `OIDCClient` for Epinio's Dex, either via `kubectl` or through the Rancher UI (**☰ → Users & Authentication → OIDC Apps → Add Application**):
41+
42+
[Configure Rancher as an OIDC Provider](https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/configure-oidc-provider)
43+
44+
When creating the client, set the **redirect URI** to match Dex's callback URL:
45+
46+
```
47+
https://auth.<your-epinio-domain>/callback
48+
```
49+
50+
Once created, note the generated **client ID** and **client secret** — you will need both for the Dex connector configuration in the next step.
51+
52+
## Step 2: Configure the Dex OIDC Connector
53+
54+
Edit the `config.yaml` key inside the `dex-config` secret in the `epinio` namespace. Add (or update) an OIDC connector block pointing at Rancher.
55+
56+
```yaml
57+
connectors:
58+
- type: oidc
59+
id: rancher
60+
name: Rancher
61+
config:
62+
issuer: https://<rancher-url>/oidc
63+
clientID: <client-id-from-step-1>
64+
clientSecret: <client-secret-from-step-1>
65+
redirectURI: https://auth.<your-epinio-domain>/callback
66+
67+
# Rancher's OIDC provider only supports these scopes.
68+
# Requesting others (e.g., "email", "groups") will cause errors.
69+
scopes:
70+
- openid
71+
- profile
72+
- offline_access
73+
74+
# Required: Rancher does not return groups in the standard scopes.
75+
# This tells Dex to request them outside of the normal scope flow.
76+
insecureEnableGroups: true
77+
78+
# Claim mapping — Rancher may not return an "email" claim.
79+
# If your upstream IdP populates the "name" claim but not "email",
80+
# map it so Dex can identify the user.
81+
claimMapping:
82+
email: name
83+
```
84+
85+
### Key configuration notes
86+
87+
**Scopes:** Rancher's OIDC provider only supports `openid`, `profile`, and `offline_access`. Do not add `email` or `groups` to the `scopes` list — they are not recognized and will cause token request failures.
88+
89+
**`insecureEnableGroups`:** Because groups are not surfaced through a standard scope, this flag is required for Dex to include group information in the token. Without it, the `groups` claim will be empty even if the user belongs to groups in the upstream IdP.
90+
91+
**`claimMapping`:** Rancher's userinfo response depends on the upstream auth provider. If your provider does not populate a standard `email` claim, you need to map an alternative claim. For example, when Rancher uses GitHub auth, the `name` field is typically populated with the GitHub username, so `claimMapping.email: name` tells Dex to treat that value as the email identifier.
92+
93+
## Step 3: Group Claims and Roles Mapping
94+
95+
When Rancher's upstream auth is GitHub, group claims are returned as **numeric GitHub team IDs** in the format:
96+
97+
```
98+
github_team://123456
99+
```
100+
101+
These are not human-readable team names like `my-org:my-team`. This is a Rancher behavior — it maps GitHub teams to their numeric IDs internally.
102+
103+
To map these to Epinio roles, use the `rolesMapping` key in the `dex-config` secret. You can map both formats if you have connectors that return different group name styles:
104+
105+
```yaml
106+
rolesMapping:
107+
# From a direct GitHub connector (human-readable)
108+
"my-org:my-team":
109+
- "user"
110+
- "admin:my-namespace"
111+
112+
# From the Rancher OIDC connector (numeric GitHub team IDs)
113+
"github_team://123456":
114+
- "admin"
115+
```
116+
117+
## Step 4: Apply and Restart
118+
119+
After updating the `dex-config` secret, restart the Dex workload so it picks up the new configuration:
120+
121+
```bash
122+
kubectl rollout restart deployment dex -n epinio
123+
```
124+
125+
Verify the OIDC flow:
126+
127+
```bash
128+
epinio login --oidc https://epinio.<your-domain>
129+
```
130+
131+
This should redirect you through Dex to the Rancher login page (which in turn may redirect to your upstream IdP, e.g., GitHub OAuth).
132+
133+
## Troubleshooting
134+
135+
**"Invalid scopes" or token errors:** Verify your connector only requests `openid`, `profile`, and `offline_access`. Remove any other scopes.
136+
137+
**Groups claim is empty:** Confirm `insecureEnableGroups: true` is set in the connector config. Also verify the user actually belongs to a team/group in the upstream IdP — org-level membership alone may not populate groups.
138+
139+
**Numeric group IDs don't match:** Use the GitHub API to confirm the team ID. Rancher uses the numeric `id`, not the `slug` or display name.
140+
141+
## Related Documentation
142+
143+
- [Configure Rancher as an OIDC Provider](https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/configure-oidc-provider) (Rancher docs)
144+
- [Dex OIDC Connector](https://dexidp.io/docs/connectors/oidc/)
145+
- [OIDC authentication](../../references/authentication_oidc.md) (Epinio docs)
146+
- [Groups and roles mapping](../../references/authentication_oidc.md#groups-and-roles-mapping) (Epinio docs)

‎docs/installation/other_inst_scenarios/install_epinio_on_rancher.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,3 +106,7 @@ Once using your Epinio instance, you can deploy and delete:
106106
- applications
107107
- namespaces
108108
- configurations.
109+
110+
## Single sign-on with Rancher
111+
112+
Rancher and Epinio each integrate with your identity provider separately. To align operator sign-in with the same accounts and groups you use in Rancher, see [Rancher-aligned SSO](../../howtos/operations/configuring_rancher_sso.md).

0 commit comments

Comments
 (0)