kubectl with OpenID Connect

3 min readMar 26, 2018

TL;DR

Kubernetes supports various authentication methods including OpenID Connect. OpenID Connect allows single sign on (SSO) to a Kubernetes cluster and other development tools.

Kubernetes authentication with Google Identity Platform

In this article, we will configure the following stack:

OpenID Connect Provider
Kubernetes API Server
kubectl and kubelogin

Note: This article has been updated for the latest kubelogin on Sep 26, 2019.

Getting Started

1. Setup your OpenID Connect Provider

At first setup an OpenID Connect Provider such as Keycloak, Google Identity Provider, Azure AD and so on.

And then create a client as follows:

Client ID: kubernetes
Client Secret: YOUR_SECRET (usually generated by IdP)
Valid Redirect URIs: http://localhost:8000/

If you are using Keycloak, see also this article. You can set up a Keycloak server by the Helm chart.

If you are using Google Identity Provider, see the document for details.

2. Setup your Kubernetes API Server

Setup your Kubernetes API server to authenticate with OpenID Connect.

If you are using kops, add the following by kops edit cluster:

spec:
  kubeAPIServer:
    oidcClientID: kubernetes
    oidcGroupsClaim: groups
    oidcIssuerURL: https://keycloak.example.com/auth/realms/hello

If you are using kube-aws, add the following to cluster.yaml:

       oidc:
         enabled: true
         issuerUrl: https://keycloak.example.com/auth/realms/hello
         clientId: kubernetes
         groupsClaim: groups

Now you can access the cluster with OpenID Connect.

3. Setup kubectl with kubelogin

Install kubelogin from Homebrew or Krew:

# Homebrew
brew install int128/kubelogin/kubelogin

# Krew
kubectl krew install oidc-login

Let’s configure your ~/.kube/config to authenticate with kubelogin:

users:
- name: keycloak
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=https://issuer.example.com
      - --oidc-client-id=YOUR_CLIENT_ID
      - --oidc-client-secret=YOUR_CLIENT_SECRET

Run kubectl command.

kubectl get pods

Kubectl executes kubelogin before calling the Kubernetes APIs. Kubelogin automatically opens the browser and you can log in to the provider.

After authentication, kubelogin returns the credentials to kubectl and finally kubectl calls the Kubernetes APIs with the credential.

% kubectl get pods
Open http://localhost:8000 for authentication
You got a valid token until 2019-05-18 10:28:51 +0900 JST
Error from server (Forbidden): pods is forbidden: User "https://keycloak.example.com/auth/realms/hello#874c4a74-faf3-45a0-bcfe-9ddf4fb802ea" cannot list pods in the namespace "default"

Probably you will get Forbidden error because you have no role. If you got Unauthorized error, it means authentication failure and check your settings.

Here assign the cluster-admin role to you.

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: oidc-admin-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: User
  name: https://keycloak.example.com/auth/realms/hello#874c4a74-faf3-45a0-bcfe-9ddf4fb802ea

Make sure you can access the Kubernetes cluster:

% kubectl get pods
NAME                          READY   STATUS    RESTARTS   AGE
echoserver-86c78fdccd-nzmd5   1/1     Running   0          26d

Wrap up

In this article, I introduced how we can access a Kubernetes cluster with OpenID Connect using kubectl and kubelogin.