kubelogin: A kubectl plugin that turns OIDC browser login into a credential cache

The problem: OIDC tokens in kubectl are a manual chore

Kubernetes clusters that use OpenID Connect for authentication require a valid ID token in every API request. Without a plugin, you must obtain that token from your identity provider, copy it into your kubeconfig, and repeat that process whenever the token expires. For a short-lived token, that means interrupting your work every hour or so. kubelogin automates this by acting as a client-go credential plugin. When you run kubectl, it detects that the kubeconfig points to the plugin, launches a browser, and lets you log in to your provider. The token it receives is then used by kubectl for API calls. This is aimed at developers and platform engineers who use kubectl daily against clusters that enforce OIDC, and who do not want to fiddle with token files or manual refresh.

How the credential plugin flow works

The README describes the mechanism clearly. kubelogin is designed to run as a client-go credential plugin. Your kubeconfig specifies an exec section that points to the plugin with arguments like `--oidc-issuer-url` and `--oidc-client-id`. When you run `kubectl get pods`, kubectl invokes the plugin before making any API call. The plugin opens a browser at a local URL, for example `http://localhost:8000`, where you authenticate. After you log in, kubelogin receives the authorization code and exchanges it for tokens. It then returns the credentials to kubectl, which uses them to call the Kubernetes API. The plugin caches the ID token and refresh token. On subsequent invocations, it checks whether the ID token is still valid. If it is, it simply returns it. If it has expired, it uses the refresh token to obtain a new ID token. Only when the refresh token is also expired does it trigger a full browser re-authentication. This three-tier flow minimizes how often you see a browser window.

Getting it running: install methods and kubeconfig setup

The README lists several installation paths. On macOS and Linux you can use Homebrew with `brew install kubelogin`. For Kubernetes users who already have Krew, the command is `kubectl krew install oidc-login`, which works on macOS, Linux, Windows, and ARM. Windows users can also use Chocolatey with `choco install kubelogin`. If you download a release binary from GitHub, you must name it `kubectl-oidc_login` and place it on your PATH so that kubectl can find it by its plugin naming convention. The other methods handle this naming for you. After installation, your kubeconfig needs an exec entry. The README shows a minimal example: the user entry specifies `command: kubectl`, with arguments `oidc-login get-token --oidc-issuer-url=ISSUER_URL --oidc-client-id=YOUR_CLIENT_ID`. You also need to configure the OIDC provider, cluster role binding, and the API server itself. The README points to a setup guide for the full details. One useful command is `kubectl oidc-login setup`, which dumps the ID token claims so you can verify that your provider configuration is correct.

Token cache: file system vs keyring

By default, kubelogin stores the token cache on the file system. The README gives the path as `/home/user/.kube/cache/oidc-login` in the example. This is convenient because it survives across terminal sessions, but it means your ID token and refresh token sit in a plain file. The README recommends using the keyring for enhanced security, without spelling out the exact configuration key. The `clean` command deletes the token cache, both from the file system and from the keyring if you use one. That is how you log out. If you are logged in to the provider in a browser and you run `clean`, kubelogin will ask you to log in again, but the browser may still have a session cookie. The README warns that you need to log out from the provider or clear the cookie in that case. This is a small but real usability trap for users who share a browser profile with their personal account.

Limitations and failure modes

The most obvious limitation is that kubelogin requires a browser. The README's example shows it opening `http://localhost:8000`, which means you need a graphical environment or at least a way to forward that port. In a headless CI environment or on a remote server over SSH without X forwarding, the browser flow will not work. The README mentions a standalone mode in the docs, but the main README does not describe it, so you would need to read the separate document to see if it supports a device flow or a manual token paste. Another failure mode is refresh token expiry. The README says that if the refresh token has expired, kubelogin performs re-authentication. If your provider issues short-lived refresh tokens, or if you revoke them, users will see a browser prompt more often than expected. Also, the token cache is per user and per cluster, so if you switch between clusters with different OIDC providers, you may end up with multiple cache entries. The README does not discuss how the cache key is computed, so you should test that yourself.

Alternatives: what else does OIDC for kubectl?

The main alternative is the Kubernetes built-in OIDC authentication, where you manually obtain a token and put it in your kubeconfig as a `token` field. That approach works without any plugin, but it requires manual refresh and does not handle the browser flow at all. Another option is `kubelogin`'s predecessor or sibling tools like `oidc-login` from the Kubernetes ecosystem, but those are essentially the same codebase. A more different approach is using a service account token instead of OIDC, which avoids the browser entirely but gives up the benefits of federated identity. There is also the possibility of using a kubectl proxy that injects tokens, but that adds a moving part. The key difference with kubelogin is that it is a client-go credential plugin, which means kubectl invokes it on every command, so the token is always fresh without you having to think about it. The manual token approach is simpler to set up but fails the moment the token expires, which for many providers is within an hour.

Maintenance and license considerations

The project is written in Go and licensed under Apache-2.0, which is permissive and allows commercial use with attribution. The repository is actively maintained, with the latest release v1.36.3 pushed in July 2026, and previous releases in May and April of the same year. That cadence of roughly monthly releases suggests that bugs and Kubernetes version changes are addressed promptly. The README mentions acceptance tests against identity providers, which is a good sign for compatibility, but it also means you should test with your specific provider before rolling out. The upgrade cost is low because it is a single binary that you replace. The kubeconfig exec entry does not change between versions unless the plugin API changes, which is unlikely given that it uses `client.authentication.k8s.io/v1`. One thing to verify is whether the binary you install via Homebrew or Krew stays in sync with the latest GitHub release, because the README lists all three as valid but does not say which one is updated first.

Editorial conclusion

Adopt kubelogin if you manage Kubernetes clusters that authenticate users via OIDC and you want a browser-based login that does not require manually copying tokens into kubeconfig. Skip it if your provider does not support the authorization code flow with PKCE, or if you need to run kubectl in a headless environment without a browser. Before adopting, verify that your OIDC provider issues refresh tokens, because without them kubelogin will force a full re-authentication each time the ID token expires. Also check the token cache location: the default file-based cache is convenient but stores tokens in plain text, so consider switching to the keyring if your security policy demands it. The project is actively maintained with regular releases, so the upgrade path is straightforward, but you should test the `setup` command against your provider before rolling it out to your team.

Official sources

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