Set up a custom identity provider

Kyma sits on top of Kubernetes and leverages authentication strategies from it. The purpose of all of those authentication strategies is to associate the identity of the caller with the request to the API server and evaluate access based on roles (RBAC).

One of the strategies enables you to use your own identity provider. This is very convenient because you can delegate the verification of who the users are to a separate user management entity and even reuse it in different systems.

NOTE: Kubernetes supports OpenID Connect (OIDC) JWT Access tokens, so make sure your identity provider is OIDC-compliant.


  • Generate a kubeconfig file for the Kubernetes cluster that hosts the Kyma instance.
  • Use an OIDC-compliant identity provider.


Configure your identity provider

NOTE: If you don't have access to the identity provider, you can sign up for a free tier plan at Auth0.

Configure a dedicated client (often referred to as an application) at your identity provider.

  1. Save these details of your application at your identity provider:
  • issuerUrl
  • clientId
  • clientSecret
  1. Add http://localhost:8000 to the allowed redirect URLs that are required for the OIDC login plugin.
  2. Configure the name of the username and group claims.
  3. Enable the Proof Key for Code Exchange (PKCE) authentication flow.

Configure your identity provider as the OIDC server

Add flags to the API server as described in the Kubernetes documentation. The ways of adding the flags to the API server differ depending on the Kubernetes distribution you use. For example, if you want to use k3d, you need to pass the additional --k3s-server-arg flags containing the OIDC server configuration when creating the cluster. See the specification of the k3d cluster create command:

Click to copy
k3d cluster create kyma \
--k3s-server-arg "--kube-apiserver-arg=oidc-issuer-url=<your-ipd-issuer-url>" \
--k3s-server-arg "--kube-apiserver-arg=oidc-username-claim=<username-claim-at-your-ipd>" \
--k3s-server-arg "--kube-apiserver-arg=oidc-client-id=<your-ipd-client-id>" \
--k3s-server-arg "--kube-apiserver-arg=oidc-groups-claim=<group-claim-at-your-ipd>" \

For managed Kubernetes, see the documentation related to your provider. For example, if you use Gardener as a managed Kubernetes offering, see the OIDC Preset documentation.

Configure role-based access to identities provided by your OIDC server

Including the JWT token in the call to the API server, enables the API server to validate and extract the associated identity from the username and group claims of the JWT token.

Now, define which individuals or groups should have access to which Kyma resources. The default setup does not provide access to any. You need to model permissions using the RBAC concept.

By default, Kyma comes with the following ClusterRoles:

  • kyma-admin - gives full admin access to the entire cluster
  • kyma-namespace-admin - gives full admin access to the specific Namespace
  • kyma-edit - gives full access to all Kyma-managed resources
  • kyma-developer - gives full access to Kyma-managed resources and basic Kubernetes resources
  • kyma-view - allows viewing and listing all of the resources in the cluster
  • kyma-essentials - gives a set of minimal view access rights to use in Kyma Dashboard

To bind a user to the kyma-admin ClusterRole, run this command:

Click to copy
kubectl create clusterrolebinding {BINDING_NAME} --clusterrole=kyma-admin --user={USERNAME AS IDENTIFIED AT YOUR IDP}

To check if the binding is created, run:

Click to copy
kubectl get clusterrolebinding {BINDING_NAME}

To bind a group of users to the kyma-admin ClusterRole, run this command:

Click to copy
kubectl create clusterrolebinding {BINDING_NAME} --clusterrole=kyma-admin --group={GROUPNAME}

You can combine user-level and group-level permissions in one binding. Run kubectl create clusterrolebinding --help in your terminal to see more options.

Configure kubectl access

With this step, you will set up the OIDC provider in the kubeconfig file to enforce authentication flow when accessing Kyma using kubectl.

  1. Install the kubelogin plugin.
  2. Copy your current kubeconfig file into a new file.
  3. In the new kubeconfig file, define a new OIDC user and set up the OIDC provider.

    Click to copy
    - name: oidc
    command: kubectl
    - oidc-login
    - get-token
    - --oidc-issuer-url=ISSUER_URL
    - --oidc-client-id=YOUR_CLIENT_ID

    NOTE: The --oidc-client-secret=YOUR_CLIENT_SECRET is not required if your OICS server supports the PKCE authentication flow.

  4. To enforce the OIDC login, set the OIDC user as a default user in the context.

    Click to copy
    cluster: {YOUR_CLUSTER_NAME}
    user: oidc
  5. Now, you can share the modified kubeconfig file with the members of your team or organization. When they use it, your identity provider will handle the authentication. The Kubernetes API server will make sure they have access to resources according to the roles bound to them as individuals or group members.