kubelogin

This is a kubectl plugin for Kubernetes OpenID Connect (OIDC) authentication. It gets a token from the OIDC provider and writes it to the kubeconfig.

Getting Started

You need to setup the following components:

OIDC provider
Kubernetes API server
Role for your group or user
kubectl authentication

You can install the latest release from Homebrew, Krew or GitHub Releases as follows:

# Homebrew
brew tap int128/kubelogin
brew install kubelogin

# Krew
kubectl krew install oidc-login

# GitHub Releases
curl -LO https://github.com/int128/kubelogin/releases/download/v1.9.1/kubelogin_linux_amd64.zip
unzip kubelogin_linux_amd64.zip
ln -s kubelogin kubectl-oidc_login

After initial setup or when the token has been expired, just run:

% kubelogin
2019/04/09 13:33:37 Using current-context: hello.k8s.local
2019/04/09 13:33:38 Open http://localhost:8000 for authorization
2019/04/09 13:33:44 Got a token for subject=1234567890
2019/04/09 13:33:44 Updated .kubeconfig

or run as a kubectl plugin:

% kubectl oidc-login

It opens the browser and you can log in to the provider. After authentication, it gets an ID token and refresh token and writes them to the kubeconfig.

For more, see the following documents:

Configuration

This supports the following options.

  kubelogin [OPTIONS]

Application Options:
      --kubeconfig=               Path to the kubeconfig file (default: ~/.kube/config) [$KUBECONFIG]
      --listen-port=              Port used by kubelogin to bind its webserver (default: 8000) [$KUBELOGIN_LISTEN_PORT]
      --insecure-skip-tls-verify  If set, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
                                  [$KUBELOGIN_INSECURE_SKIP_TLS_VERIFY]
      --skip-open-browser         If set, it does not open the browser on authentication. [$KUBELOGIN_SKIP_OPEN_BROWSER]

Help Options:
  -h, --help        Show this help message

This also supports the following keys of auth-provider in kubeconfig. See kubectl authentication.

Key	Direction	Value
`idp-issuer-url`	Read (Mandatory)	Issuer URL of the provider.
`client-id`	Read (Mandatory)	Client ID of the provider.
`client-secret`	Read (Mandatory)	Client Secret of the provider.
`idp-certificate-authority`	Read	CA certificate path of the provider.
`idp-certificate-authority-data`	Read	Base64 encoded CA certificate of the provider.
`extra-scopes`	Read	Scopes to request to the provider (comma separated).
`id-token`	Write	ID token got from the provider.
`refresh-token`	Write	Refresh token got from the provider.

Kubeconfig path

You can set the environment variable KUBECONFIG to point the config file. Default to ~/.kube/config.

export KUBECONFIG="$PWD/.kubeconfig"

Extra scopes

You can set extra scopes to request to the provider by extra-scopes in the kubeconfig.

kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=email

Note that kubectl does not accept multiple scopes and you need to edit the kubeconfig as like:

kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=SCOPES
sed -i '' -e s/SCOPES/email,profile/ $KUBECONFIG

CA Certificates

You can set your self-signed certificates for the OIDC provider (not Kubernetes API server) by idp-certificate-authority and idp-certificate-authority-data in the kubeconfig.

kubectl config set-credentials keycloak \
  --auth-provider-arg idp-certificate-authority=$HOME/.kube/keycloak-ca.pem

If kubelogin could not parse the certificate, it shows a warning and skips it.

HTTP Proxy

You can set the following environment variables if you are behind a proxy: HTTP_PROXY, HTTPS_PROXY and NO_PROXY. See also net/http#ProxyFromEnvironment.

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.

irons / kubelogin