README
¶
kubelogin 
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:
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:
Getting Started
Setup
Install the latest release from Homebrew, Krew, Chocolatey or GitHub Releases.
# 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.
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:
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 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.
After the authentication, kubelogin returns the credentials to kubectl. Kubectl then calls the Kubernetes APIs with the credentials.
% 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
Kubelogin stores the token cache to the file system by default. For enhanced security, it is recommended to store it to the keyring. See the token cache for details.
You can log out by deleting the token cache.
% kubectl oidc-login clean
Deleted the token cache at /home/user/.kube/cache/oidc-login
Deleted the token cache from 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.
% 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.
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 to verify if kubelogin works with your provider.
Docs
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.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
integration_test
|
|
|
httpdriver
Package httpdriver provides a test double of the browser.
|
Package httpdriver provides a test double of the browser. |
|
oidcserver
Package oidcserver provides a stub of OpenID Connect provider.
|
Package oidcserver provides a stub of OpenID Connect provider. |
|
oidcserver/handler
Package handler provides HTTP handlers for the OpenID Connect Provider.
|
Package handler provides HTTP handlers for the OpenID Connect Provider. |
|
mocks
|
|
|
pkg
|
|
|
credentialplugin
Package credentialplugin provides the types for client-go credential plugins.
|
Package credentialplugin provides the types for client-go credential plugins. |
|
credentialplugin/reader
Package reader provides a loader for the credential plugin.
|
Package reader provides a loader for the credential plugin. |
|
credentialplugin/writer
Package writer provides a writer for the credential plugin.
|
Package writer provides a writer for the credential plugin. |
|
infrastructure/clock
Package clock provides the system clock.
|
Package clock provides the system clock. |
|
infrastructure/reader
Package reader provides the reader of standard input.
|
Package reader provides the reader of standard input. |
|
infrastructure/stdio
Package stdio wraps os.Stdin and os.Stdout for testing.
|
Package stdio wraps os.Stdin and os.Stdout for testing. |
|
jwt
Package jwt provides JWT manipulations.
|
Package jwt provides JWT manipulations. |
|
oidc/client
Package client provides a client of OpenID Connect.
|
Package client provides a client of OpenID Connect. |
|
pkce
Package pkce provides generation of the PKCE parameters.
|
Package pkce provides generation of the PKCE parameters. |
|
testing/httpserver
command
|
|
|
tlsclientconfig/loader
Package loader provides loading certificates from files or base64 encoded string.
|
Package loader provides loading certificates from files or base64 encoded string. |
|
usecases/credentialplugin
Package credentialplugin provides the use-cases for running as a client-go credentials plugin.
|
Package credentialplugin provides the use-cases for running as a client-go credentials plugin. |
|
usecases/setup
Package setup provides the use case of setting up environment.
|
Package setup provides the use case of setting up environment. |
|
system_test
|
|
|
login/chromelogin
command
|