int128/kubelogin: a kubectl credential plugin for OpenID Connect

The gap kubelogin fills between kubectl and an OIDC issuer

Kubernetes can accept OpenID Connect tokens at the API server, but kubectl has no built-in way to obtain one. Someone has to run the authorization code flow, open a browser, catch the redirect, and hand the resulting ID token back to kubectl in the format client-go expects. kubelogin exists to do exactly that step.

The README describes it as a kubectl plugin for Kubernetes OpenID Connect authentication, also known as `kubectl oidc-login`. It is aimed at platform engineers and developers who already have an OIDC provider (the README's example uses the Google Identity Platform) and a cluster whose API server trusts that issuer. If your cluster authenticates with client certificates or static service account tokens, kubelogin has nothing to do.

The design choice worth noting is that kubelogin does not proxy Kubernetes API calls. It runs, returns credentials, and exits. Everything else stays with kubectl and client-go.

How the exec credential plugin flow actually runs

The README states that kubelogin is designed to run as a client-go credential plugin. The mechanism is a subprocess contract: kubeconfig declares a command under `users[].user.exec`, and kubectl invokes that command before it talks to the API server.

Kubeconfig points at kubectl itself with `oidc-login get-token` as arguments, which is why the binary must be named `kubectl-oidc_login` when installed manually. kubectl finds plugins by the naming convention, so `kubectl oidc-login` resolves to that file on your PATH.

The data flow, as the README describes it: kubelogin opens the browser, you log in to the provider, kubelogin gets a token from the provider, and kubectl then calls the Kubernetes APIs with that token. The README's console example shows `Open http://localhost:8000 for authentication` printed before the pod list appears.

Caching is the part that matters day to day. The README says kubelogin stores the ID token and refresh token in a cache. A valid ID token is returned as is. An expired ID token is refreshed with the refresh token. When the refresh token has also expired, kubelogin performs full re-authentication. That three-state ladder is the whole reason repeated `kubectl get pods` calls do not each open a browser tab.

Installing kubelogin on macOS, Linux and Windows

The README lists four install paths: Homebrew, Krew, Chocolatey, and GitHub Releases. Homebrew covers macOS and Linux, Krew covers macOS, Linux, Windows and ARM, and Chocolatey covers Windows. Pick one; they all place the binary where kubectl can find it.

# Homebrew (macOS and Linux)
brew install kubelogin

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

# Chocolatey (Windows)
choco install kubelogin

If you install from GitHub Releases instead, the README is explicit: save the binary as the name `kubectl-oidc_login` on your path. That naming is what makes `kubectl oidc-login` work, and it is the usual cause of a `kubelogin not found` error after a manual download.

The second half of setup is kubeconfig. The README gives this shape, with the issuer URL and client ID replaced by your own values:

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

The README points to docs/setup.md for the rest, which includes the provider, cluster role binding, and API server configuration. Those pieces are outside the plugin and the README does not reproduce them.

With that in place, run kubectl normally:

kubectl get pods

You should see the authentication URL printed, then the pod list once you finish in the browser. On a first run the browser opens; on later runs a cached ID token usually means no browser at all.

Debugging claims with the setup command

The setup command is the most useful thing here after installation. It runs the flow and dumps the ID token claims, which is what you need when the cluster rejects a token that the provider issued happily.

% kubectl oidc-login setup --oidc-issuer-url=ISSUER_URL --oidc-client-id=REDACTED
...
You got a token with the following claims:

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

Compare `iss` and `aud` against the `--oidc-issuer-url` and `--oidc-client-id` your API server was started with. The README also documents `-v1` for a higher log level, set in the same args list:

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

There is also an acceptance_test directory, which the README suggests running to verify that kubelogin works with your provider. That is a cheaper check than discovering a mismatch through failed kubectl calls.

Token cache security and the clean command

By default kubelogin writes the token cache to the file system. The README recommends storing it in the keyring instead, for enhanced security, and points to docs/usage.md#token-cache for the details. This is a real trade-off rather than a footnote: the file system cache is a file containing an ID token and a refresh token, and a refresh token is a long-lived credential. The keyring path depends on a platform secret store, which is why it is opt-in rather than the default.

Logging out means deleting the cache. The README's example output shows both locations being cleared:

% kubectl oidc-login clean
Deleted the token cache at /home/user/.kube/cache/oidc-login
Deleted the token cache from the keyring

One caveat the README raises directly: after cleaning, kubelogin will ask you to log in via the browser again, but if the browser still holds a cookie for the provider, you may be signed straight back in. In that case you have to log out from the provider or clear the cookie. Teams that treat `clean` as a hard logout will be surprised by this.

Where kubelogin is the wrong tool

The browser step is the limitation. kubelogin is built around an interactive authorization code flow, so it assumes a human at a machine with a browser. The README's own framing is that when you run kubectl, kubelogin opens the browser and you log in to the provider.

That makes it a poor fit for CI pipelines, cron jobs, or any unattended automation. There is no documented headless credential path in the README. If a pipeline needs to talk to an OIDC-protected cluster, the credential has to come from somewhere else.

A second constraint is that kubelogin is only the client half. The README states you need to set up the OIDC provider, cluster role binding, Kubernetes API server and kubeconfig. If you cannot change API server flags, the plugin cannot help you, no matter how it is installed.

The README also does not document rollback or cache migration between versions, so treat the cache directory as disposable state rather than something to preserve across upgrades.

How kubelogin differs from kubeconfig client certificates and static tokens

The alternative most teams already run is a kubeconfig with an embedded client certificate and key, or a static bearer token. The difference in approach is where the credential comes from. A certificate or static token is issued once and pasted into the file; it does not expire on a short schedule and it does not require a browser.

kubelogin inverts that. The credential is short-lived and minted on demand, which is the point: revocation happens at the identity provider, and the cluster trusts the issuer rather than individual credentials. The cost is the interactive step and the cache.

A middle option is a service account token, which is non-interactive and works in pipelines. It also has no dependency on an external identity provider. If your reason for considering kubelogin is simply "we want to stop distributing certificates", a service account token may cover it with less moving parts. kubelogin earns its place when you specifically want provider-issued identities mapped to cluster RBAC.

Maintenance, upgrade cost and the Apache-2.0 licence

The repository is not archived, and its last push was on 2026-07-19. Releases v1.36.3, v1.36.2 and v1.36.1 landed on 2026-07-19, 2026-05-30 and 2026-04-18 respectively, so the release cadence over that window is roughly one every six to eight weeks.

Upgrade cost is low by construction. The binary is a standalone executable, and the Dockerfile builds a static binary with CGO disabled and copies it into a distroless base image, so there is no runtime dependency chain to reconcile. The Makefile exposes `go test -v -race ./pkg/...` for unit tests, `go test -v -race ./integration_test/...` for integration tests, and `go tool golangci-lint run` for linting, which is what a contributor would run.

The practical upgrade risk is the token cache, not the binary. A newer version reading a cache written by an older one is not described in the README. The cheap mitigation is `kubectl oidc-login clean` after an upgrade, which forces a fresh login.

The project is licensed under Apache License 2.0, and the README repeats that. That is a permissive licence, but it says nothing about your identity provider's terms or your organisation's policy on storing refresh tokens in a keyring or a cache file. Those are separate questions; this is not legal advice.

Editorial conclusion

Adopt kubelogin if your API server is already configured with an OIDC issuer and you want browser-based login plus token caching instead of pasting static tokens into kubeconfig. Do not adopt it if you cannot change the API server flags or need a non-interactive credential for CI. Before rolling it out, run `kubectl oidc-login setup` against your issuer to confirm the claims your cluster role binding expects.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes