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 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.
After authentication, kubelogin returns the credentials to kubectl and kubectl then calls the Kubernetes APIs with these credentials.
% 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 re-authentication (you will have to login via browser again).
Troubleshoot
You can log out by removing the token cache directory (default ~/.kube/cache/oidc-login).
Kubelogin will ask you to login via browser again if the token cache file does not exist i.e., it starts with a clean slate
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
- Setup guide
- Usage and options
- Standalone mode (deprecated)
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.16+ is required.
make
./kubelogin
See also:
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 a HTTP handler for the OpenID Connect Provider.
|
Package handler provides a HTTP handler for the OpenID Connect Provider. |
|
oidcserver/http
Package http provides a http server running on localhost for testing.
|
Package http provides a http server running on localhost for testing. |
|
pkg
|
|
|
credentialplugin
Package credentialplugin provides the types for client-go credential plugins.
|
Package credentialplugin provides the types for client-go credential plugins. |
|
credentialplugin/writer
Package writer provides a writer for a credential plugin.
|
Package writer provides a writer for a credential plugin. |
|
credentialplugin/writer/mock_writer
Package mock_writer is a generated GoMock package.
|
Package mock_writer is a generated GoMock package. |
|
infrastructure/browser/mock_browser
Package mock_browser is a generated GoMock package.
|
Package mock_browser is a generated GoMock package. |
|
infrastructure/clock
Package clock provides the system clock.
|
Package clock provides the system clock. |
|
infrastructure/mutex/mock_mutex
Package mock_mutex is a generated GoMock package.
|
Package mock_mutex is a generated GoMock package. |
|
infrastructure/reader
Package reader provides the reader of standard input.
|
Package reader provides the reader of standard input. |
|
infrastructure/reader/mock_reader
Package mock_reader is a generated GoMock package.
|
Package mock_reader is a generated GoMock package. |
|
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. |
|
kubeconfig/loader/mock_loader
Package mock_loader is a generated GoMock package.
|
Package mock_loader is a generated GoMock package. |
|
kubeconfig/writer/mock_writer
Package mock_writer is a generated GoMock package.
|
Package mock_writer is a generated GoMock package. |
|
oidc/client
Package client provides a client of OpenID Connect.
|
Package client provides a client of OpenID Connect. |
|
oidc/client/mock_client
Package mock_client is a generated GoMock package.
|
Package mock_client is a generated GoMock package. |
|
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. |
|
tokencache/repository/mock_repository
Package mock_repository is a generated GoMock package.
|
Package mock_repository is a generated GoMock package. |
|
usecases/authentication/mock_authentication
Package mock_authentication is a generated GoMock package.
|
Package mock_authentication is a generated GoMock package. |
|
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/credentialplugin/mock_credentialplugin
Package mock_credentialplugin is a generated GoMock package.
|
Package mock_credentialplugin is a generated GoMock package. |
|
usecases/setup
Package setup provides the use case of setting up environment.
|
Package setup provides the use case of setting up environment. |
|
usecases/standalone/mock_standalone
Package mock_standalone is a generated GoMock package.
|
Package mock_standalone is a generated GoMock package. |
|
system_test
|
|
|
login/chromelogin
command
|