Awesome Open Source
Awesome Open Source

kubelogin CircleCI Go Report Card

This is a kubectl plugin for Kubernetes OpenID Connect (OIDC) authentication, also known as kubectl oidc-login.

Here is an example of Kubernetes authentication with the Google Identity Platform:

screencast

Kubelogin is designed to run as a client-go credential plugin. When you run kubectl, kubelogin opens the browser and you can log in to the provider. Then kubelogin gets a token from the provider and kubectl access Kubernetes APIs with the token. Take a look at the diagram:

Diagram of the credential plugin

Getting Started

Setup

Install the latest release from Homebrew, Krew, Chocolatey or GitHub Releases.

# Homebrew (macOS and Linux)
brew install int128/kubelogin/kubelogin

# Krew (macOS, Linux, Windows and ARM)
kubectl krew install oidc-login

# Chocolatey (Windows)
choco install kubelogin

You need to set up the OIDC provider, cluster role binding, Kubernetes API server and kubeconfig. The kubeconfig looks like:

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

See setup guide for more.

Run

Run kubectl.

kubectl get pods

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

keycloak-login

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
NAME                          READY   STATUS    RESTARTS   AGE
echoserver-86c78fdccd-nzmd5   1/1     Running   0          26d

Kubelogin writes the ID token and refresh token to the token cache file.

If the cached ID token is valid, kubelogin just returns it. If the cached ID token has expired, kubelogin will refresh the token using the refresh token. If the refresh token has expired, kubelogin will perform reauthentication.

Troubleshoot

You can log out by removing the token cache directory (default ~/.kube/cache/oidc-login). Kubelogin will perform authentication if the token cache file does not exist.

You can dump claims of an ID token by setup command.

% kubectl oidc-login setup --oidc-issuer-url https://accounts.google.com --oidc-client-id REDACTED --oidc-client-secret REDACTED
...
You got a token with the following claims:

{
  "sub": "********",
  "iss": "https://accounts.google.com",
  "aud": "********",
  ...
}

You can increase the log level by -v1 option.

users:
- name: oidc
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
      - oidc-login
      - get-token
      - -v1

You can verify kubelogin works with your provider using acceptance test.

Docs

Related works

Kubernetes Dashboard

You can access the Kubernetes Dashboard using kubelogin and kauthproxy.

Contributions

This is an open source software licensed under Apache License 2.0. Feel free to open issues and pull requests for improving code and documents.

Your pull request will be merged into master with squash.

Development

Go 1.15+ is required.

make
./kubelogin

See also:


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
go (14,148
golang (3,605
kubernetes (1,609
kubectl (76
openid-connect (60
oidc (37
kubectl-plugins (26

Find Open Source By Browsing 7,000 Topics Across 59 Categories