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 anid_token
,access_token
, andrefresh_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:
- In the top left corner, click ☰ > Users & Authentication.
- In the left navigation menu, click OIDC Apps.
- Click Add Application. Fill out the Create OIDC App form.
- 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.