From c1161bc21ec3928690006deac084ac5d92ecf425 Mon Sep 17 00:00:00 2001 From: raul Date: Thu, 26 Jun 2025 15:23:38 +0200 Subject: [PATCH 1/4] OIDC provider doc --- .../configure-oidc-provider.md | 138 ++++++++++++++++++ sidebars.js | 1 + 2 files changed, 139 insertions(+) create mode 100644 docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md diff --git a/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md new file mode 100644 index 000000000000..00b6ff7235af --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -0,0 +1,138 @@ +--- +title: Configure Rancher as an OIDC provider +--- + + + + + +Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication. +This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/next/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. + +The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: + +`https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes. + +`https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an id_token, access_token, and refresh_token. + +`https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details. + +`https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user. + +The OIDC provider supports the OIDC Authentication Code Flow with PKCE. + +## Configure OIDCClient + +An `OIDCClient` represents an external application that will be authenticating against Rancher. + +### Programmatically + +Create an `OIDCClient`: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +``` +Rancher automatically generates a client ID and client secret for each `OIDCClient`. +Once the resource is created, Rancher populates the status field with the client id: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +status: + clientID: client-xxx + clientSecrets: + client-secret-1: + createdAt: "xxx" + lastFiveCharacters: xxx +``` + +Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. +Initially, the `Secret` contains a single client secret. + +To retrieve the client secret: + +``` +kubectl get secret client-xxx -n cattle-oidc-client-secrets -o jsonpath="{.data.client-secret-1}" | base64 -d +``` + +Output: + +``` +secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +You can now use this client ID and client secret in your OIDC client application. + +#### Managing Client Secrets + +You can manage multiple client secrets per `OIDCClient`. Use annotations on the `OIDCClient` resource to perform secret operations: + +- Creation: Adding the `cattle.io/oidc-client-secret-create: true` annotation triggers the creation of a new client secret. +- Removal: Adding the `cattle.io/oidc-client-secret-remove:client-secret-1` annotation removes the specified client secrets. +- Regeneration: Adding the `cattle.io/oidc-client-secret-regenerate:client-secret-1` annotation regenerates the specified client secrets. + +### Rancher UI + +Create an OIDCClient: + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **OIDC Apps**. +1. Click **Add Application**. Fill out the **Create OIDC App** form. +1. Click **Add Application**. + +#### Managing Client Secrets + +In the OIDC App page: + +- Creation: Click **Add new secret**. +- Removal: Click **⋮ > Delete** +- Regeneration: Click **⋮ > Regenerate** + +## Signing key + +A default key pair for signing the `id_token`, `access_token`, and `refresh_token` tokens is created by Rancher in a `Secret` called `oidc-signing-key` in the `cattle-system` namespace. Only one key will be used for signing, but multiple public keys can be returned in the jwks endpoint in order to avoid disruption when doing a key rotation. + +### Rotation without disruption + +In order to create a new key pair for signing you need to manually create a new keypair and add it to the `oidc-signing-key` `Secret` + +Example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: oidc-signing-key +type: Opaque +data: + key2.pem: + key1.pub: + key2.pub: +``` + +Rancher will sign tokens using `key2.pem`, while the JWKS endpoint will serve both `key1.pub` and `key2.pub`. This ensures a smooth +key rotation from `key1` to `key2` without disrupting existing token verification. Note that only one private key (.pem) can be stored in the +secret at a time, and each key pair must share the same base name, differing only by their suffix: .pem for the private key and .pub for the public key. + +### Rotation with disruption + +Removing the `oidc-signing-key` `Secret` will cause Rancher to regenerate the signing key on the next restart. + +:::warning +This will invalidate all previously issued `id_token`, `access_token`, and `refresh_token` tokens making them unusable. +::: diff --git a/sidebars.js b/sidebars.js index 6c39c1de6b43..d807afcd6b5d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -806,6 +806,7 @@ const sidebars = { "how-to-guides/advanced-user-guides/enable-user-retention", "how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization", "how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer", + "how-to-guides/advanced-user-guides/configure-oidc-provider", ] } ] From 127c0a6c3430fd642b0898b17c3702afea19321a Mon Sep 17 00:00:00 2001 From: Raul Cabello Martin Date: Thu, 3 Jul 2025 10:06:33 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Petr Kovar --- .../advanced-user-guides/configure-oidc-provider.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md index 00b6ff7235af..f96a4fb92aa9 100644 --- a/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md +++ b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -11,13 +11,13 @@ This can be used for enabling single sign-on (SSO) across Rancher Prime componen The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: -`https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes. +- `https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes. -`https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an id_token, access_token, and refresh_token. +- `https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an `id_token`, `access_token`, and `refresh_token`. -`https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details. +- `https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details. -`https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user. +- `https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user. The OIDC provider supports the OIDC Authentication Code Flow with PKCE. @@ -90,7 +90,7 @@ You can manage multiple client secrets per `OIDCClient`. Use annotations on the Create an OIDCClient: -1. In the top left corner, click **☰ > Users & Authentication**. +1. In the top left corner, click **☰ > Users & Authentication**. 1. In the left navigation menu, click **OIDC Apps**. 1. Click **Add Application**. Fill out the **Create OIDC App** form. 1. Click **Add Application**. From 614fcac22b661710c1ad8c457465b5f7da1199af Mon Sep 17 00:00:00 2001 From: raul Date: Thu, 3 Jul 2025 10:09:05 +0200 Subject: [PATCH 3/4] copy OIDC provider doc to /versioned_docs/version-2.12/how-to-guides/advanced-user-guides --- .../configure-oidc-provider.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 versioned_docs/version-2.12/how-to-guides/advanced-user-guides/configure-oidc-provider.md diff --git a/versioned_docs/version-2.12/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/versioned_docs/version-2.12/how-to-guides/advanced-user-guides/configure-oidc-provider.md new file mode 100644 index 000000000000..f96a4fb92aa9 --- /dev/null +++ b/versioned_docs/version-2.12/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -0,0 +1,138 @@ +--- +title: Configure Rancher as an OIDC provider +--- + + + + + +Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication. +This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/next/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. + +The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: + +- `https://{rancher-url}/oidc/authorize`: This endpoint initiates the authentication flow. If a user is already logged into Rancher, it returns an authorization code. Otherwise, it redirects the user to the Rancher login page. Authorization codes and related request information are securely stored in session secrets. Codes are single-use and expire after 10 minutes. + +- `https://{rancher-url}/oidc/token`: This endpoint exchanges an authorization code for an `id_token`, `access_token`, and `refresh_token`. + +- `https://{rancher-url}/oidc/.well-known/openid-configuration`: This endpoint returns a JSON document containing the OIDC provider's configuration, including endpoint URLs, supported scopes, claims, and other relevant details. + +- `https://{rancher-url}/oidc/userinfo`: This endpoint provides information about the authenticated user. + +The OIDC provider supports the OIDC Authentication Code Flow with PKCE. + +## Configure OIDCClient + +An `OIDCClient` represents an external application that will be authenticating against Rancher. + +### Programmatically + +Create an `OIDCClient`: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +``` +Rancher automatically generates a client ID and client secret for each `OIDCClient`. +Once the resource is created, Rancher populates the status field with the client id: + +```yaml +apiVersion: management.cattle.io/v3 +kind: OIDCClient +metadata: + name: oidc-client-test +spec: + tokenExpirationSeconds: 600 # expiration of the id_token and access_token + refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token + redirectURIs: + - "https://myredirecturl.com" # replace with your redirect url +status: + clientID: client-xxx + clientSecrets: + client-secret-1: + createdAt: "xxx" + lastFiveCharacters: xxx +``` + +Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. +Initially, the `Secret` contains a single client secret. + +To retrieve the client secret: + +``` +kubectl get secret client-xxx -n cattle-oidc-client-secrets -o jsonpath="{.data.client-secret-1}" | base64 -d +``` + +Output: + +``` +secret-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +You can now use this client ID and client secret in your OIDC client application. + +#### Managing Client Secrets + +You can manage multiple client secrets per `OIDCClient`. Use annotations on the `OIDCClient` resource to perform secret operations: + +- Creation: Adding the `cattle.io/oidc-client-secret-create: true` annotation triggers the creation of a new client secret. +- Removal: Adding the `cattle.io/oidc-client-secret-remove:client-secret-1` annotation removes the specified client secrets. +- Regeneration: Adding the `cattle.io/oidc-client-secret-regenerate:client-secret-1` annotation regenerates the specified client secrets. + +### Rancher UI + +Create an OIDCClient: + +1. In the top left corner, click **☰ > Users & Authentication**. +1. In the left navigation menu, click **OIDC Apps**. +1. Click **Add Application**. Fill out the **Create OIDC App** form. +1. Click **Add Application**. + +#### Managing Client Secrets + +In the OIDC App page: + +- Creation: Click **Add new secret**. +- Removal: Click **⋮ > Delete** +- Regeneration: Click **⋮ > Regenerate** + +## Signing key + +A default key pair for signing the `id_token`, `access_token`, and `refresh_token` tokens is created by Rancher in a `Secret` called `oidc-signing-key` in the `cattle-system` namespace. Only one key will be used for signing, but multiple public keys can be returned in the jwks endpoint in order to avoid disruption when doing a key rotation. + +### Rotation without disruption + +In order to create a new key pair for signing you need to manually create a new keypair and add it to the `oidc-signing-key` `Secret` + +Example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: oidc-signing-key +type: Opaque +data: + key2.pem: + key1.pub: + key2.pub: +``` + +Rancher will sign tokens using `key2.pem`, while the JWKS endpoint will serve both `key1.pub` and `key2.pub`. This ensures a smooth +key rotation from `key1` to `key2` without disrupting existing token verification. Note that only one private key (.pem) can be stored in the +secret at a time, and each key pair must share the same base name, differing only by their suffix: .pem for the private key and .pub for the public key. + +### Rotation with disruption + +Removing the `oidc-signing-key` `Secret` will cause Rancher to regenerate the signing key on the next restart. + +:::warning +This will invalidate all previously issued `id_token`, `access_token`, and `refresh_token` tokens making them unusable. +::: From 01d1daaac74c98874f15cba865d4a0099beb591d Mon Sep 17 00:00:00 2001 From: raul Date: Thu, 3 Jul 2025 15:34:29 +0200 Subject: [PATCH 4/4] add OIDC provider to 2.12 sidebars --- versioned_sidebars/version-2.12-sidebars.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versioned_sidebars/version-2.12-sidebars.json b/versioned_sidebars/version-2.12-sidebars.json index 1aa118c964ec..69d013d0934e 100644 --- a/versioned_sidebars/version-2.12-sidebars.json +++ b/versioned_sidebars/version-2.12-sidebars.json @@ -769,7 +769,8 @@ "how-to-guides/advanced-user-guides/enable-api-audit-log-in-downstream-clusters", "how-to-guides/advanced-user-guides/enable-user-retention", "how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization", - "how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer" + "how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer", + "how-to-guides/advanced-user-guides/configure-oidc-provider" ] } ]