OIDC Provider Configuration
This manual explains how to configure a custom OIDC provider to use with Kubermatic Kubernetes Platform (KKP).
When nothing is configured, KKP uses
https://<domain>/dex as the OIDC provider
URL, which by default points to Dex. The domain is taken from the
When redirecting users to the OIDC provider for login into the KKP dashboard, KKP
adds the following parameters to the base URL:
&response_type is set to
&client_id is set to
&redirect_uri is set to
https://<domain>/projects which is root view of the KKP dashboard
&scope is set to
openid email profile groups
&nonce is randomly generated, 32 character string to prevent replay attacks
The default configuration can be changed as KKP supports other OIDC providers as well. This
involves updating the KKP dashboard and API using the
KubermaticConfiguration CRD on the
master cluster. The used configuration can be retrieved using
kubectl -n kubermatic get kubermaticconfigurations
kubectl -n kubermatic get kubermaticconfiguration kubermatic -o yaml
# - operator.kubermatic.io/cleanup
# name: kubermatic
# namespace: kubermatic
# issuerClientSecret: abcd1234
# issuerCookieKey: wxyz9876
# serviceAccountKey: 2468mnop
There are two sections to update.
The KKP API validates the given token for authentication and therefore needs to be able to
find the new token issuer. The relevant fields are under
spec.auth and the following snippet
demonstrates the default values:
tokenIssuer needs to be updated, the rest can be left out if the default values are
used. This gives us:
The KKP dashboard needs to know where to redirect the user to in order to perform a
login. This can be set by setting a
spec.ui.config field, containing JSON. This is where
various UI-related options can be set, among them:
oidc_provider is the name of the OIDC provider. UI will configure workflows like sign-in, sign-out, etc based on the provider. Currently, only dex and keycloak are supported.
oidc_provider_url to change the base URL of the OIDC provider.
oidc_provider_scope to change the scope of the OIDC provider. (the
scope URL parameter)
oidc_provider_client_id to change the client of the OIDC provider.
oidc_connector_id to use a default connector of the OIDC provider.
oidc_logout_url to redirect to logout URL of the OIDC provider. (available in
A configuration of a custom OIDC provider may look like this:
"oidc_provider_scope": "openid email profile roles",
Applying the Changes
Edit the KubermaticConfiguration either directly via
kubectl edit or apply it from a YAML
file by using
kubectl apply. The KKP Operator will pick up on the changes and
reconfigure the components accordingly. After a few seconds the new pods should be up and
If you are using Keycloak as a custom OIDC provider, make sure that you set the option
Implicit Flow Enabled: On
kubermaticIssuer clients. Without this option, you won’t be properly
redirected to the login page.