Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/int128/kubelogin

kubectl plugin for Kubernetes OpenID Connect authentication (kubectl oidc-login)
https://github.com/int128/kubelogin

golang kubectl kubectl-plugins kubernetes oidc openid-connect

Last synced: 3 days ago
JSON representation

kubectl plugin for Kubernetes OpenID Connect authentication (kubectl oidc-login)

Host: GitHub
URL: https://github.com/int128/kubelogin
Owner: int128
License: apache-2.0
Created: 2018-03-21T10:37:15.000Z (almost 7 years ago)
Default Branch: master
Last Pushed: 2025-01-21T11:06:51.000Z (11 days ago)
Last Synced: 2025-01-21T15:04:25.452Z (11 days ago)
Topics: golang, kubectl, kubectl-plugins, kubernetes, oidc, openid-connect
Language: Go
Homepage:
Size: 2.78 MB
Stars: 1,806
Watchers: 16
Forks: 198
Open Issues: 90
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

awesome-repositories - int128/kubelogin - kubectl plugin for Kubernetes OpenID Connect authentication (kubectl oidc-login) (Go)
awesome-devops - kubelogin - kubectl plugin for Kubernetes OpenID Connect authentication (kubectl oidc-login) (Kubernetes / Kubernetes // Authentication)
awesome-kubectl-plugins - kubelogin - login) | Authn/Authz | [![GitHub stars](https://img.shields.io/github/stars/int128/kubelogin)](https://github.com/int128/kubelogin/stargazers) | (kubectl Plugins / Installing plugins via awesome-kubectl-plugins)

README

# kubelogin [![go](https://github.com/int128/kubelogin/actions/workflows/go.yaml/badge.svg)](https://github.com/int128/kubelogin/actions/workflows/go.yaml) [![Go Report Card](https://goreportcard.com/badge/github.com/int128/kubelogin)](https://goreportcard.com/report/github.com/int128/kubelogin)

This is a kubectl plugin for [Kubernetes OpenID Connect (OIDC) authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens), 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](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
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](docs/credential-plugin-diagram.svg)

## Getting Started

### Setup

Install the latest release from [Homebrew](https://brew.sh/), [Krew](https://github.com/kubernetes-sigs/krew), [Chocolatey](https://chocolatey.org/packages/kubelogin) or [GitHub Releases](https://github.com/int128/kubelogin/releases).

```sh
# 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 via GitHub releases, save the binary as the name `kubectl-oidc_login` on your path.
When you invoke `kubectl oidc-login`, kubectl finds it by the [naming convention of kubectl plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/).
The other install methods do this for you.

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

```yaml
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
```

See the [setup guide](docs/setup.md) for more.

### Run

Run kubectl.

```sh
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 the authentication, kubelogin returns the credentials to kubectl.
Kubectl then calls the Kubernetes APIs with the credentials.

```console
% kubectl get pods
Open http://localhost:8000 for authentication
NAME READY STATUS RESTARTS AGE
echoserver-86c78fdccd-nzmd5 1/1 Running 0 26d
```

Kubelogin stores the ID token and refresh token to the cache.
If the ID token is valid, it just returns it.
If the ID token has expired, it will refresh the token using the refresh token.
If the refresh token has expired, it will perform re-authentication.

## Troubleshooting

### Token cache

If the OS keyring is available, kubelogin stores the token cache to the OS keyring.
Otherwise, kubelogin stores the token cache to the file system.
See the [token cache](docs/usage.md#token-cache) for details.

You can log out by deleting the token cache.

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

Kubelogin will ask you to log in via the browser again.
If the browser has a cookie for the provider, you need to log out from the provider or clear the cookie.

### ID token claims

You can run `setup` command to dump the claims of an ID token from the provider.

```console
% 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": "********",
...
}
```

You can set `-v1` option to increase the log level.

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

You can run the [acceptance test](acceptance_test) to verify if kubelogin works with your provider.

## Docs

- [Setup guide](docs/setup.md)
- [Usage and options](docs/usage.md)
- [Standalone mode](docs/standalone-mode.md)
- [System test](system_test)
- [Acceptance_test for identity providers](acceptance_test)

## 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.