kubectl with OpenID Connect

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.

Login page of Keycloak

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.

See also

Software Engineer at https://github.com/int128

Software Engineer at https://github.com/int128