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 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:

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:

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.
2. In the left navigation menu, click OIDC Apps.
3. Click Add Application. Fill out the Create OIDC App form.
4. 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:

apiVersion: v1
kind: Secret
metadata:
 name: oidc-signing-key
type: Opaque
data:
 key2.pem: <base64-encoded-new-private-key>
 key1.pub: <base64-encoded-old-public-key>
 key2.pub: <base64-encoded-new-public-key>

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.

危险

This will invalidate all previously issued id_token, access_token, and refresh_token tokens making them unusable.