Authentication
Introduction
This page explains how to authenticate to the Kubernetes API using a kubeconfig file. This file stores authentication and connection information used by tools like kubectl and Helm to access your cluster. While the examples focus on kubectl, the same configuration can be used by other tools that interact with the cluster programmatically. If you are only using the KKP Dashboard, you are already authenticated through your browser session and do not need a kubeconfig.
Quick Guide for the Impatient Reader
To get started, log in to SCK, navigate to the Resources > Clusters tab and click Get Kubeconfig to download the kubeconfig file. By default, kubectl uses the file ~/.kube/config. You can set the environment variable in your current shell session to point to the downloaded file:
This avoids modifying your default configuration. Then you can test the access by running:
Example output
Any member of your KKP project — or anyone with whom the kubeconfig download link was shared — can download the kubeconfig file for a cluster, and use that file to authenticate with a user name corresponding to their primary Switch edu-ID email address. Being authenticated does not automatically grant access to cluster resources. To perform actions like viewing worker nodes or managing workloads, you must also be authorized — that is, be granted appropriate cluster privileges by your KKP project member who has Owner or Editor role assigned. If you are authenticated but not authorized, you may see something like this:
Example output
Kubernetes Users
Kubernetes clusters have two categories of users:
-
Normal user (user): A human user not managed by Kubernetes itself. These accounts authenticate via external systems and interact using tools like
kubectlor the KKP Dashboard. Throughout this documentation, the term user refers to a normal (human) user. -
Service account (SA): An account managed by Kubernetes and intended for use by workloads such as Pods, controllers, or CI/CD pipelines. SAs are not meant to represent human identities, but may be used in automation or scripts triggered by users. Learn more about Kubernetes service accounts use cases.
For more details see Users in Kubernetes.
Important
Please note that KKP also introduces the concept of service accounts which is something totally different from Kubernetes service accounts. KKP SAs can use a long-lived token to authenticate with the KKP API. You can create a KKP SA and add a long-lived token using the Access > Service Accounts tab.
Kubernetes has no built-in mechanism for managing normal users or groups. It relies entirely on external systems to handle authentication and group membership. As a result, you cannot list users or groups from within Kubernetes (for example, using kubectl).
Once a user is authenticated, the identity is passed to the Kubernetes API server as a simple string. From there, Role-Based Access Control (RBAC) determines whether that user is authorized to perform specific actions.
Normal User Authentication
Before interacting with a cluster, you first have to set up authentication in the kubeconfig file. Kubernetes supports numerous authentication strategies. If interested, you can get an overview at Authentication Strategies.
The preferred SCK user authentication strategy for normal users uses OpenID Connect Tokens.
OpenID Connect Tokens
SCK clusters can validate OIDC tokens issued by https://auth.sck.cloud.switch.ch/. This is a Switch edu-ID OIDC proxy.
Log in to SCK, navigate to the Resources > Clusters tab and click Get Kubeconfig to download the kubeconfig file.
Sample kubeconfig
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: [REDACTED]
server: https://<cluster_api_endpoint>
name: <cluster_id>
contexts:
- context:
cluster: <cluster_id>
user: <user_email>
name: <context_name>
current-context: <context_name>
kind: Config
preferences: {}
users:
- name: <user_email>
user:
auth-provider:
config:
client-id: [REDACTED]
client-secret: [REDACTED]
id-token: [REDACTED]
idp-issuer-url: https://auth.sck.cloud.switch.ch/
refresh-token: [REDACTED]
name: oidc
Once downloaded, the kubeconfig file contains two important tokens:
-
id-token: Valid for 24 hours, used to authenticate your CLI requests. -
refresh-token: Valid for 30 days, allowskubectlto automatically renew theid-tokenwhen it expires.
As long as the refresh-token is still valid and the file is saved in a writable location, kubectl handles the token refresh automatically in the background.
Warning
If you download a new kubeconfig file, a new refresh-token is issued, and all previously issued ones are invalidated — even those from other clusters. This means that older configs will stop working after their id-token expires unless updated with a new refresh-token.
If your refresh-token expires or becomes invalid, download a new kubeconfig and either use it directly or update your existing one with the new refresh-token and id-token.
Multicluster Configuration
If you are working with multiple clusters, it is best to combine them into a single kubeconfig file and use the most recently downloaded id-token and refresh-token. This avoids conflicts and ensures continued access without authentication errors. Below is a sample multicluster kubeconfig that defines access to two Kubernetes clusters using a single user identity:
Sample multicluster kubeconfig
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: [REDACTED]
server: https://<cluster_api_endpoint_1>
name: <cluster_id_1>
- cluster:
certificate-authority-data: [REDACTED]
server: https://<cluster_api_endpoint_2>
name: <cluster_id_2>
contexts:
- context:
cluster: <cluster_id_1>
user: <user_email>
name: <context_name_1>
- context:
cluster: <cluster_id_2>
user: <user_email>
name: <context_name_2>
current-context: <context_name_1>
users:
- name: <user_email>
user:
auth-provider:
config:
client-id: [REDACTED]
client-secret: [REDACTED]
id-token: [REDACTED]
idp-issuer-url: https://auth.sck.cloud.switch.ch/
refresh-token: [REDACTED]
name: oidc
Each context links a cluster with the user account, allowing you to switch between clusters.
You can list all available contexts with:
Example output
You can check the current context with:
You can switch contexts using:
You can easily integrate a newly downloaded kubeconfig into your default ~/.kube/config by running:
KUBECONFIG=~/.kube/config:<downloaded_file_path> kubectl config view --flatten > ~/.kube/.config.tmp
mv ~/.kube/.config.tmp ~/.kube/config
Tip
Switching between clusters using kubectl config use-context can be cumbersome, especially when managing multiple environments. You might want to consider installing kubectx as a more user-friendly alternative.
Kubernetes Service Accounts
To create a Kubernetes service account, navigate to the Resources > Clusters tab and select your cluster from the list. Select the RBAC tab at the bottom of the page and click Add Service Account. In the popup window enter a Name, select a Namespace and click Add Service Account. You can now download a kubeconfig file for your service account by clicking the Download Kubeconfig button far right in the relevant row of the RBAC table and use it to authenticate your service account.