From 692022f5c69b8169a5737fcb21d24be1fc1b9857 Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Thu, 24 Sep 2026 09:30:55 +0200 Subject: [PATCH 1/4] Document Rancher OIDC groups scope configuration --- .../setup/security/authentication/oidc.adoc | 38 +++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc index 7a39635cf..89488d399 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc @@ -1,6 +1,6 @@ = Open ID Connect (OIDC) :page-languages: [en, de, es, fr, ja, pt, zh] -:revdate: 2025-07-10 +:revdate: 2026-09-24 :page-revdate: {revdate} :description: SUSE Observability Self-hosted @@ -17,7 +17,8 @@ Before you can configure SUSE Observability to authenticate using OIDC, you need [NOTE] This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. -Create an OIDCClient resource in the Rancher local cluster: +For Rancher 2.14 or later, create an OIDCClient resource with the following scopes in the Rancher local cluster. +For Rancher 2.12 and 2.13, omit `spec.scopes` from this example; these versions do not support the `groups` scope. [,yaml] ---- apiVersion: management.cattle.io/v3 @@ -25,6 +26,7 @@ kind: OIDCClient metadata: name: oidc-observability spec: + scopes: [openid, profile, offline_access, groups] tokenExpirationSeconds: 600 refreshTokenExpirationSeconds: 3600 redirectURIs: @@ -39,6 +41,7 @@ kind: OIDCClient metadata: name: oidc-observability spec: + scopes: [openid, profile, offline_access, groups] tokenExpirationSeconds: 600 refreshTokenExpirationSeconds: 3600 redirectURIs: @@ -76,7 +79,9 @@ The result of this configuration should produce a *clientId* and a *secret*. Cop [NOTE] This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. -To configure Rancher as the OIDC provider for SUSE Observability, you need to add the OIDC details to the authentication values: +For Rancher 2.14 or later, add the following OIDC configuration to your authentication values. +The `stackstate.authentication.rancher.scope` option is available from SUSE Observability {next-release-version}. +For Rancher 2.12 and 2.13, omit `scope` to retain the existing behavior. [,yaml] ---- stackstate: @@ -85,6 +90,7 @@ stackstate: clientId: "" secret: "" baseUrl: "" + scope: [openid, profile, offline_access, groups] # oidcLogout and skipLoginPage are optional and both default to false #_ oidcLogout: false #_ skipLoginPage: false @@ -94,6 +100,7 @@ You can override and extend the OIDC config for Rancher with the following field * **discoveryUri** - URI that you can use to discover the OIDC provider. Normally, also documented or returned when creating the client in the OIDC provider. * **redirectUri** - Optional (not in the example): The URI where the login callback endpoint of SUSE Observability is reachable. Populated by default using the `stackstate.baseUrl`, but can be overridden. This must be a fully qualified URL that points to the `/loginCallback` path. * **customParameters** - Optional map of key/value pairs that you send to the OIDC provider as custom request parameters. Certain OIDC providers require extra request parameters not sent by default. +* **scope** - Optional array containing `openid` and any of `profile`, `offline_access`, and `groups`. When omitted, the chart requests `[openid, profile, offline_access]`. Every requested scope must be allowed by the Rancher OIDCClient. * **oidcLogout** - Optional (default `false`): when set to `true`, logging out of {stackstate-product-name} also logs the user out of the OIDC provider. When `false`, logging out only ends the {stackstate-product-name} session. * **skipLoginPage** - Optional (default `false`): when set to `true`, the {stackstate-product-name} login page is skipped and users are redirected straight to the OIDC provider. @@ -102,6 +109,31 @@ You can override and extend the OIDC config for Rancher with the following field Setting `oidcLogout: false` and `skipLoginPage: true` will cause the logout process to immediately redirect to the OIDC provider and re-authenticate, which will make it appear that the user was not logged out. ==== +==== Upgrade Rancher and retain group access + +When upgrading Rancher to 2.14 or later, update both the existing OIDCClient and the SUSE Observability configuration. +Rancher 2.15 and later require the `groups` scope to return group claims. +Without it, group-based access can disappear while direct user assignments and Rancher's own group permissions still work. + +. First, update the existing OIDCClient through the configuration that manages your Rancher local cluster. + Set `spec.scopes` to include `openid`, `profile`, `offline_access`, and `groups`. + Preserve any other scopes that the client requires. + An empty `spec.scopes` uses defaults without `groups`. + Requesting `groups` before allowing it on the client can fail login with `invalid_scope`. +. Upgrade to SUSE Observability {next-release-version} or later, and set `stackstate.authentication.rancher.scope` to `[openid, profile, offline_access, groups]`. + Keep the existing client ID, secret, and Rancher URL. +. After the Helm rollout completes, log out of SUSE Observability and log in again. + An existing session does not establish that the new scope works. +. Check that the authorization request contains `groups` in its `scope` parameter. + Check that the new session contains the expected group identities. +. With a user whose access comes from an existing group binding, check that the expected resources are accessible. + Direct user assignments alone do not test group access. + +The Rancher preset keeps `usernameField = "sub"` and `groupsField = "groups"`. +Do not change these claim mappings or switch to the generic OIDC configuration for this upgrade. + +==== TLS verification + If you need to disable TLS verification due to a setup not using verifiable SSL certificates, you can disable SSL checks with application config (don't use in production): For **Non-HA** Setup: From 03eee9b367039b862d0bfd5ca6f011f4e95bf384 Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Thu, 24 Sep 2026 12:31:00 +0200 Subject: [PATCH 2/4] Update Rancher OIDC docs with known issues --- .../authentication_options.adoc | 1 + .../setup/security/authentication/oidc.adoc | 27 ++++++++---------- .../authentication/troubleshooting.adoc | 28 +++++++++++++++++++ 3 files changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/security/authentication/authentication_options.adoc b/docs/latest/modules/en/pages/setup/security/authentication/authentication_options.adoc index ddb2f8557..6768e7697 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/authentication_options.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/authentication_options.adoc @@ -11,6 +11,7 @@ For better security SUSE Observability can be configured to use exactly one of t * xref:/setup/security/authentication/single_password.adoc[Single password] * xref:/setup/security/authentication/file.adoc[File based] * xref:/setup/security/authentication/ldap.adoc[LDAP] +* xref:/setup/security/authentication/oidc.adoc#_rancher[Rancher (OIDC)] * xref:/setup/security/authentication/oidc.adoc[Open ID Connect (OIDC)] * xref:/setup/security/authentication/keycloak.adoc[KeyCloak (a specialized version of OIDC)] diff --git a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc index 89488d399..97cecb78e 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc @@ -15,7 +15,7 @@ Before you can configure SUSE Observability to authenticate using OIDC, you need === Rancher [NOTE] -This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. +This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known-issues[Known issues]. For Rancher 2.14 or later, create an OIDCClient resource with the following scopes in the Rancher local cluster. For Rancher 2.12 and 2.13, omit `spec.scopes` from this example; these versions do not support the `groups` scope. @@ -77,7 +77,7 @@ The result of this configuration should produce a *clientId* and a *secret*. Cop === Rancher [NOTE] -This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. +This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known-issues[Known issues]. For Rancher 2.14 or later, add the following OIDC configuration to your authentication values. The `stackstate.authentication.rancher.scope` option is available from SUSE Observability {next-release-version}. @@ -115,22 +115,17 @@ When upgrading Rancher to 2.14 or later, update both the existing OIDCClient and Rancher 2.15 and later require the `groups` scope to return group claims. Without it, group-based access can disappear while direct user assignments and Rancher's own group permissions still work. -. First, update the existing OIDCClient through the configuration that manages your Rancher local cluster. - Set `spec.scopes` to include `openid`, `profile`, `offline_access`, and `groups`. - Preserve any other scopes that the client requires. - An empty `spec.scopes` uses defaults without `groups`. +* First, update the existing OIDCClient through the configuration that manages your Rancher local cluster. + Set `spec.scopes` to include `openid`, `profile`, `offline_access`, and `groups`. You can patch the existing client with: +[,bash] +---- +kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge -p '{"spec":{"scopes":["openid","profile","offline_access","groups"]}}' +---- + Requesting `groups` before allowing it on the client can fail login with `invalid_scope`. -. Upgrade to SUSE Observability {next-release-version} or later, and set `stackstate.authentication.rancher.scope` to `[openid, profile, offline_access, groups]`. +* Upgrade to SUSE Observability {next-release-version} or later, and set `stackstate.authentication.rancher.scope` to `[openid, profile, offline_access, groups]`. Keep the existing client ID, secret, and Rancher URL. -. After the Helm rollout completes, log out of SUSE Observability and log in again. - An existing session does not establish that the new scope works. -. Check that the authorization request contains `groups` in its `scope` parameter. - Check that the new session contains the expected group identities. -. With a user whose access comes from an existing group binding, check that the expected resources are accessible. - Direct user assignments alone do not test group access. - -The Rancher preset keeps `usernameField = "sub"` and `groupsField = "groups"`. -Do not change these claim mappings or switch to the generic OIDC configuration for this upgrade. +* After the Helm rollout completes, log out of SUSE Observability and log in again to verify that the group-based access is working correctly after updating the scope. ==== TLS verification diff --git a/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc b/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc index 2e8cdb62d..ead7029bb 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc @@ -35,6 +35,34 @@ Now run the `helm upgrade` command you used before but include this one extra ya To disable the debug logging run the `+helm upgrade ....+` command again but omit the `--values debug-auth.yaml`. After 30 seconds the updated logging configuration is loaded and the debug logging stops. +== Known issues + +With Rancher authentication users don't get permissions assigned to their groups. This is caused by a missing `groups` scope. Rancher 2.14 introduced this `groups` scope. In SUSE Observability versions < {next-release-version} the `groups` scope is not set and is also not configurable. Here is a work-around for older SUSE Observability versions + +1. Update the OIDC Client configuration in Rancher: ++ +[,bash] +---- + kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge -p '{"spec":{"scopes":["openid","profile","offline_access","groups"]}}' +---- + +2. Update the SUSE Observability configuration, remove the `stackstate.authentication.rancher` section and replace it with the normal OIDC configuration as shown below: ++ +[,yaml] +---- +stackstate: + authentication: + oidc: + clientId: "" + secret: "" + discoveryUri: https:///oidc/.well-known/openid-configuration + scope: [openid, profile, offline_access, groups] + jwsAlgorithm: RS256 + jwtClaims: + usernameField: sub + groupsField: groups +---- + == Troubleshooting issues with permissions * xref:/setup/security/rbac/rbac_permissions.adoc#_list_subjects_for_a_user[Inspect the user subjects] (user and roles) and verify the configuration depending on the authentication model being used. From bb9c61dd4683426c775a06de70f97977238f874f Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Thu, 24 Sep 2026 16:59:19 +0200 Subject: [PATCH 3/4] Fix links and code block --- .../setup/security/authentication/oidc.adoc | 6 ++--- .../authentication/troubleshooting.adoc | 24 ++++++++++++++----- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc index 97cecb78e..c9b66207e 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc @@ -15,7 +15,7 @@ Before you can configure SUSE Observability to authenticate using OIDC, you need === Rancher [NOTE] -This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known-issues[Known issues]. +This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known_issues[Known issues]. For Rancher 2.14 or later, create an OIDCClient resource with the following scopes in the Rancher local cluster. For Rancher 2.12 and 2.13, omit `spec.scopes` from this example; these versions do not support the `groups` scope. @@ -77,7 +77,7 @@ The result of this configuration should produce a *clientId* and a *secret*. Cop === Rancher [NOTE] -This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known-issues[Known issues]. +This only works with Rancher 2.12 or later. You need to https://documentation.suse.com/cloudnative/rancher-manager/latest/en/rancher-admin/users/authn-and-authz/configure-oidc-provider.html[configure Rancher as an OIDC provider]. If group permissions are not working please check xref:/setup/security/authentication/troubleshooting.adoc#_known_issues[Known issues]. For Rancher 2.14 or later, add the following OIDC configuration to your authentication values. The `stackstate.authentication.rancher.scope` option is available from SUSE Observability {next-release-version}. @@ -117,12 +117,12 @@ Without it, group-based access can disappear while direct user assignments and R * First, update the existing OIDCClient through the configuration that manages your Rancher local cluster. Set `spec.scopes` to include `openid`, `profile`, `offline_access`, and `groups`. You can patch the existing client with: ++ [,bash] ---- kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge -p '{"spec":{"scopes":["openid","profile","offline_access","groups"]}}' ---- - Requesting `groups` before allowing it on the client can fail login with `invalid_scope`. * Upgrade to SUSE Observability {next-release-version} or later, and set `stackstate.authentication.rancher.scope` to `[openid, profile, offline_access, groups]`. Keep the existing client ID, secret, and Rancher URL. * After the Helm rollout completes, log out of SUSE Observability and log in again to verify that the group-based access is working correctly after updating the scope. diff --git a/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc b/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc index ead7029bb..16b662ed8 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc @@ -37,25 +37,33 @@ To disable the debug logging run the `+helm upgrade ....+` command again but omi == Known issues -With Rancher authentication users don't get permissions assigned to their groups. This is caused by a missing `groups` scope. Rancher 2.14 introduced this `groups` scope. In SUSE Observability versions < {next-release-version} the `groups` scope is not set and is also not configurable. Here is a work-around for older SUSE Observability versions +Rancher 2.15 and later require the `groups` scope to return group claims. +Without it, users can lose permissions assigned through groups while direct user assignments still work. +The `groups` scope is available from Rancher 2.14. +For SUSE Observability installations whose Rancher preset cannot configure scopes (any version up to 2.11.2), use the following workaround. -1. Update the OIDC Client configuration in Rancher: +1. Update the existing OIDCClient in the Rancher local cluster to allow the required scopes. + [,bash] ---- - kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge -p '{"spec":{"scopes":["openid","profile","offline_access","groups"]}}' +kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge -p '{"spec":{"scopes":["openid","profile","offline_access","groups"]}}' ---- - -2. Update the SUSE Observability configuration, remove the `stackstate.authentication.rancher` section and replace it with the normal OIDC configuration as shown below: ++ +An empty `spec.scopes` defaults to a list without `groups`. +2. Remove `stackstate.authentication.rancher` from your SUSE Observability values and replace it with the generic OIDC configuration below. + Keep your existing client ID and secret, and use your Rancher URL in `discoveryUri`. + Preserve any custom redirect URI, logout options, and custom parameters under `oidc`. + Keep existing role and group bindings. + [,yaml] ---- stackstate: authentication: + sessionLifetime: "16h" oidc: clientId: "" secret: "" - discoveryUri: https:///oidc/.well-known/openid-configuration + discoveryUri: https:///oidc/.well-known/openid-configuration scope: [openid, profile, offline_access, groups] jwsAlgorithm: RS256 jwtClaims: @@ -63,6 +71,10 @@ stackstate: groupsField: groups ---- +3. Apply the values with your usual Helm upgrade procedure. + After the rollout, log out of SUSE Observability and log in again. + Check that the new session contains the expected group identities and grants access through an existing group binding. + == Troubleshooting issues with permissions * xref:/setup/security/rbac/rbac_permissions.adoc#_list_subjects_for_a_user[Inspect the user subjects] (user and roles) and verify the configuration depending on the authentication model being used. From b8972ed862c38738c31ec1a7e756eef9cbac39e9 Mon Sep 17 00:00:00 2001 From: Remco Beckers Date: Fri, 25 Sep 2026 09:09:17 +0200 Subject: [PATCH 4/4] Link to workaround from upgrade rancher section --- .../modules/en/pages/setup/security/authentication/oidc.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc index c9b66207e..dce502f8a 100644 --- a/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc +++ b/docs/latest/modules/en/pages/setup/security/authentication/oidc.adoc @@ -124,7 +124,7 @@ kubectl patch oidcclients.management.cattle.io oidc-observability --type=merge - ---- * Upgrade to SUSE Observability {next-release-version} or later, and set `stackstate.authentication.rancher.scope` to `[openid, profile, offline_access, groups]`. - Keep the existing client ID, secret, and Rancher URL. + Keep the existing client ID, secret, and Rancher URL. If you cannot upgrade SUSE Observability at the same time follow the xref:/setup/security/authentication/troubleshooting.adoc#_known_issues[workaround described in the troubleshooting section]. * After the Helm rollout completes, log out of SUSE Observability and log in again to verify that the group-based access is working correctly after updating the scope. ==== TLS verification