kubelogin

The system test automates the end-to-end OIDC authentication flow. It prepares a local environment by:

1. Generating CA and TLS server certificates for Dex.
2. Running Dex in a container.
3. Creating a Kubernetes cluster via Kind.
4. Mutating /etc/hosts in both the host machine and the Kind container to ensure Dex is resolvable by both the browser and the kube-apiserver.

The Authentication Flow:

1. kubectl is executed, which triggers kubelogin.
2. kubelogin invokes chromelogin to open a browser.
3. The user enters credentials at http://localhost:8000.
4. kubelogin captures the authorization code and exchanges it for a token.
5. kubectl uses the token to access the API.
6. kube-apiserver verifies the token against Dex.
7. The test succeeds if kubectl exits with code 0.

The Device Authorization Grant (RFC 8628) is useful for devices that cannot easily use a browser. Set --grant-type=device-code to enable this flow.

Kubelogin will attempt to open the browser automatically. If you need to change the browser or prevent it from opening, use --browser-command or --skip-open-browser.

- --grant-type=device-code
- --browser-command=google-chrome
- --skip-open-browser

The Client Credentials Flow is used for machine-to-machine authentication. Set --grant-type=client-credentials to use this flow. This flow only returns authorization tokens per the OAuth 2.0 specification.

- --grant-type=client-credentials

Add an oidc user to your kubeconfig using the kubectl config set-credentials command. This configures kubectl to use kubelogin (via the oidc-login get-token command) to fetch authentication tokens.

Security Recommendation: Use --token-cache-storage=keyring to store the token cache in the system keyring instead of the file system for better security.

kubectl config set-credentials oidc \
  --exec-interactive-mode=Never \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=ISSUER_URL \
  --exec-arg=--oidc-client-id=YOUR_CLIENT_ID

You can install kubelogin using several package managers depending on your operating system. If you install manually via GitHub releases, you must name the binary kubectl-oidc_login and ensure it is in your system PATH so that kubectl can discover it as a plugin.

# Homebrew (macOS and Linux)
brew install kubelogin

# Krew (macOS, Linux, Windows and ARM)
kubectl krew install oidc-login

# Chocolatey (Windows)
choco install kubelogin

To use kubelogin's standalone mode, your kubeconfig user section must include an auth-provider with the name: oidc and the required configuration keys. After authentication, kubelogin will inject id-token and refresh-token into this same config block.

users:
  - name: keycloak
    user:
      auth-provider:
        config:
          client-id: YOUR_CLIENT_ID
          client-secret: YOUR_CLIENT_SECRET
          idp-issuer-url: https://issuer.example.com
          id-token: ey... # kubelogin will add or update the ID token here
          refresh-token: ey... # kubelogin will add or update the refresh token here
        name: oidc

To remove the generated test cluster and clean up the local directory, run the following commands:

make delete-cluster
make clean

This is the default flow (--grant-type=authcode). It starts a local server to receive the redirect from the provider.

• Redirect URIs: You must register http://localhost:8000 and http://localhost:18000 with your provider.
• Custom Listening Address: Use --listen-address to change the port.
• Custom Redirect URL: Use --oidc-redirect-url to override the default.
• HTTPS for Local Server: If your provider requires HTTPS for the redirect, provide certificates using --local-server-cert and --local-server-key.

- --listen-address=127.0.0.1:12345
- --oidc-redirect-url=http://127.0.0.1:8000/
- --local-server-cert=localhost.crt
- --local-server-key=localhost.key

To grant permissions to an OIDC user, create a clusterrolebinding. The user name must follow the format ISSUER_URL#YOUR_SUBJECT.

kubectl create clusterrolebinding oidc-cluster-admin --clusterrole=cluster-admin --user='ISSUER_URL#YOUR_SUBJECT'

To use kubelogin for OIDC authentication with kubectl, you must configure your kubeconfig to use an exec credential plugin. This allows kubectl to call kubelogin (via the oidc-login get-token command) to retrieve authentication tokens automatically.

Use the following command structure to set up the oidc credentials. Note that you must append any additional flags required by your specific OIDC provider (such as --oidc-issuer-url or --oidc-client-id) as --exec-arg parameters.

kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=Never \
  --exec-command=kubectl \
  --exec-arg=oidc-login \
  --exec-arg=get-token \
  --exec-arg="--oidc-issuer-url=https://example.com" \
  --exec-arg="--oidc-client-id=your-client-id"