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 7a39635cf..dce502f8a 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 @@ -15,9 +15,10 @@ 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]. -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: @@ -74,9 +77,11 @@ 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]. -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,26 @@ 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`. 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"]}}' +---- + +* 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. 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 + 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: 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..16b662ed8 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,46 @@ 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 + +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 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"]}}' +---- ++ +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 + scope: [openid, profile, offline_access, groups] + jwsAlgorithm: RS256 + jwtClaims: + usernameField: sub + 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.