Skip to content

Rancher SSO

Rancher authenticates against Microsoft Entra ID via OIDC instead of its own local user store. See Entra for the tenant-side setup (app registration, groups, Vault paths) this depends on, and On-Prem Active Directory for where app-rancher-admins itself is created and managed — it's an on-prem AD group synced up by Cloud Sync, not a cloud-only Entra group. The matching azuread_app_role_assignment on Rancher's service principal is also what makes its tile appear on My Apps.

Unlike ArgoCD, Rancher's auth config is a native resource against Rancher's own management API (rancher2_auth_config_generic_oidc, terraform/vsphere/compute/dke_mgmt.tf), not a Helm value — none of Rancher's deploy manifests needed to change.

resource "rancher2_auth_config_generic_oidc" "entra" {
  client_id     = data.vault_kv_secret_v2.entra_sso.data["rancher_oidc_client_id"]
  client_secret = data.vault_kv_secret_v2.entra_sso.data["rancher_oidc_client_secret"]
  rancher_url   = "${data.vault_kv_secret_v2.rancher.data["rancher_url"]}/verify-auth"

  issuer            = "https://login.microsoftonline.com/<tenant-id>/v2.0"
  auth_endpoint     = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize"
  token_endpoint    = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
  userinfo_endpoint = "https://graph.microsoft.com/oidc/userinfo"
  jwks_url          = "https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys"

  scopes               = "openid profile email"
  groups_field         = "groups"
  group_search_enabled = true
  access_mode          = "unrestricted"
}

Three gotchas

Provider version predates the resource

The provider rancher/rancher2 does not support resource type "rancher2_auth_config_generic_oidc" — this resource was added in provider v13.0.0+ (aligned with Rancher 2.13.x); the repo had 8.0.0 pinned. Bumped terraform/vsphere/compute/provider.tf to >= 13.0.0 and ran terraform init -upgrade. Worth a careful plan review after a 5-major-version jump — schema changes can affect already-applied resources (rancher2_bootstrap, rancher2_setting), not just add the new one.

name isn't a settable field

"name": this field cannot be set — auth config resources are singletons (one config per type in a given Rancher instance), so name is computed, not an input. Just omit it.

Group claim never reaches Rancher

Unresolved. After a real OIDC login, Rancher's own /v3/users API showed only a genericoidc_user://... principal on the user record — no genericoidc_group://... principal at all, despite group_search_enabled and groups_field/groupsClaim being verified correctly set on both the Entra app registration (group_membership_claims) and Rancher's own effective auth config (confirmed via GET /v3/genericoidcConfigs/genericoidc). Leading theory, unconfirmed without enabling Rancher debug logging: Microsoft's graph.microsoft.com/oidc/userinfo endpoint returns only a minimal standard claim set and doesn't include custom/directory claims like groups — if Rancher's generic OIDC implementation sources group membership from that endpoint rather than the ID token, that would fully explain it.

Workaround in place: rancher2_global_role_binding.psharma_admin binds the Admin global role directly to psharma's verified genericoidc_user:// principal ID (read from Rancher's own /v3/users API, not guessed — Rancher's ID format for generic-OIDC principals isn't documented anywhere the way local:// is) rather than the rancher-admins group:

resource "rancher2_global_role_binding" "psharma_admin" {
  name           = "psharma-admin"
  global_role_id = "admin"
  user_id        = "u-beqrqdjzzh"
}

Follow-up: enable Rancher debug logging for one login cycle to confirm the userinfo-endpoint theory, then fix properly and bind genericoidc_group://<ad_rancher_admins_group_id> (see vault kv get -field=ad_rancher_admins_group_id devhome/entra-sso) instead of a per-user binding.

Diagnosing via Rancher's own API

Rancher's REST API is the fastest way to check any of this directly, without waiting on a UI. Get a token as local admin, then query:

# Login as local admin
curl -sk -X POST "$RANCHER_URL/v3-public/localProviders/local?action=login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"'"$RANCHER_ADMIN_PASSWORD"'"}'

# Effective auth config
curl -sk -H "Authorization: Bearer $TOKEN" "$RANCHER_URL/v3/genericoidcConfigs/genericoidc"

# What principals a user actually ended up with after login
curl -sk -H "Authorization: Bearer $TOKEN" "$RANCHER_URL/v3/users"

The principalIds field on a user record is the definitive answer to "did group search actually work" — no guessing needed.