Skip to content


Using OIDC with kubernetes clusters


This documentation is deprecated, please check here for its new home

OIDC (OpenID Connect) provides one login for multiple sites and services. Each time a user needs to login to a website or a service using OIDC, they are redirected to their OIDC provider where they can complete the authentication process. In our case, we are able to use OIDC in order to authenticate ourselves to kubernetes clusters instead of x509 certificates.

OIDC can be used in a managed way by openstack-magnum or in an unmanaged way. Managed is recommended as it is easier but depending on your use case you may need to choose unmanaged for better granularity. This tutorial requires kubelogin. Kubelogin can be installed by running krew install oidc-login.

Managed OIDC

1) Create a cluster with OIDC enabled by setting the oidc_enabled flag to true.
$ openstack coe cluster create myClusterName --cluster-template myTemplateName --node-count 1 --labels oidc_enabled=true --merge-labels

2) Generate its config by using the --use-oidc parameter.
$ openstack coe cluster config --use-oidc myClusterName

3) During the first interaction with the cluster, executing kubectl will open a local browser with our OIDC provider so that we can complete the authentication process. Upon successful username and password submission, we will be able to use the cluster normally.

Unmanaged OIDC

We are going to assume that an application is already created in the application portal. If not, please refer to this guide.

1) Since our application is already registered in the application portal we need to make sure that the Redirect URI(s) in the SSO Registration section is either set to: - urn:ietf:wg:oauth:2.0:oob in case we want to authenticate from the command line. - http://localhost:8000 if we want our local browser to pop up automatically to get authenticated. - Both (Recommended)

OIDC Application Portal
Screenshot from the application portal

2) Create a cluster by passing the client_id of the OIDC application to the oidc_client_id label.
$ openstack coe cluster create k8s-cluster --cluster-template k8s-cluster-template --node-count 1 --labels oidc_enabled=true --labels oidc_client_id=CLIENT_ID --merge-labels

3) When the new cluster is ready, fetch its config by using the --use-oidc parameter:
$ openstack coe cluster config --use-oidc myClusterName

4) Verify access to the cluster API:
$ kubectl get nodes

Normally this will print a url that we need to copy in our browser in order to get a token that will be used for our authentication. The cluster's nodes will be printed as we are going to be authenticated.

Example Use Case: Grant pod and log access to a CERN egroup

There may be a case where the owner of the cluster may need to give limited access to a different team. This can be done by creating custom roles in our OIDC application and by adding roles and role bindings in our cluster. For a comprehensive explanation of roles and a list of steps that need to be taken in order to create them in the application portal please follow this guide.

Assuming that a custom role has been created in our application (in the application portal) and assigned to an egroup, we can proceed by adding a new namespace for the users with limited privileges.

$ kubectl create namespace limited-namespace

Create a role and a role binding.

$ cat RoleAndBinding.yaml
kind: Role
  namespace: limited-namespace
  name: pod-viewers
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]

kind: RoleBinding
  namespace: limited-namespace
  name: pod-viewers-rb
  apiGroup: ""
  kind: Role
  name: pod-viewers
- kind: Group
  name: "YOUR_ROLE_NAME"
  apiGroup: ""

$ kubectl create -f RoleAndBinding.yaml

Generate a config file and share it with other users.

$ openstack coe cluster config --use-oidc myClusterName
export KUBECONFIG=/path/to/config

$ cat /path/to/config
apiVersion: v1
- cluster:
    certificate-authority-data: BASE64_DATA
    server: https://IPOFYOURCLUSTER:6443
  name: myClusterName
- context:
    cluster: kmyClusterNameube
    user: admin
  name: default
current-context: default
kind: Config
preferences: {}
- name: admin
      - get-token
      - --oidc-issuer-url=
      - --oidc-client-id=YOUR_APP_IDENTIFIER
      - --grant-type=authcode-keyboard
      command: kubelogin
      env: null

OIDC labels for cluster creation

Label Type Description Recommended value for CERN
oidc_enabled boolean Enable or disable OIDC true
oidc_client_id string Use a custom client ID -
oidc_groups_prefix string A prefix for each group -
oidc_username_prefix string A prefix for each username -
oidc_groups_claim string Groups claim field cern_roles
oidc_username_claim string Username claim field -
oidc_issuer_url string The URL of the OIDC issuer

Parameters for OIDC cluster config

Parameter Description
--use-oidc Generate an oidc config
--oidc-browser Change the authentication to browser instead of keyboard

Last update: June 1, 2022