kubectl OIDC Authentication

kubectl OIDC Authentication

Overview

By default Kublr provisions clusters and provides two ways to access the cluster API:

  1. direct access to the managed cluster API with certificate-based authentication and cluster-admin permissions by default

  2. Kublr proxied access to the managed cluster API with Kublr OIDC authentication (as described in OpenID Connect (OIDC) authentication)

Regular Kublr users (non-admins) should use the latter method, which is documented here.

Kublr provides regular users with a kubeconfig file that includes the individual cluster Kublr API proxy endpoint, public certificates and keys, and configuration for kubelogin kubectl plugin necessary to perform OIDC authentication with Kublr OIDC identity provider.

This approach enables access by both Kublr-manages users as well as external users who log in via SSO integration with Kublr (e.g. AWS IAM, Google Apps, or Azure AD users).

The authentication flow works as wollows:

  • a user runs a kubectl command
  • kubectl calls kubelogin plugin, which opens OIDC authentication endpoint in a browser
  • the user logs into Kublr in the browser according to policies and integrations configuration in the Kublr identity provider; any SSO configuration and integrations take place at this step
  • the identity provider issues Kublr OIDC tokens and returns them to the kubelogin kubectl plugin
  • kubelogin stores the tokens and returns them to kubectl
  • kubectl sends the request along with the OIDC token to Kublr Kubernetes API proxy endpoint
  • Kublr authenticates the user using the token, and forwards the request to the cluster API with cluster-admin certificate authentication and user/group impersonation headers corresponding to the Kublr-authenticated user

Regular Kublr users (non-admins) should use the latter method, which is documented here.

Kublr provides regular users with a kubeconfig file that includes the individual cluster Kublr API proxy endpoint, public certificates and keys, and configuration for kubelogin kubectl plugin necessary to perform OIDC authentication with Kublr OIDC identity provider.

This approach enables access by both Kublr-manages users as well as external users who log in via SSO integration with Kublr (e.g. AWS IAM, Google Apps, or Azure AD users).

The authentication flow works as wollows:

  • a user runs a kubectl command
  • kubectl calls kubelogin plugin, which opens OIDC authentication endpoint in a browser
  • the user logs into Kublr in the browser according to policies and integrations configuration in the Kublr identity provider; any SSO configuration and integrations take place at this step
  • the identity provider issues Kublr OIDC tokens and returns them to the kubelogin kubectl plugin
  • kubelogin stores the tokens and returns them to kubectl
  • kubectl sends the request along with the OIDC token to Kublr Kubernetes API proxy endpoint
  • Kublr authenticates the user using the token, and forwards the request to the cluster API with cluster-admin certificate authentication and user/group impersonation headers corresponding to the Kublr-authenticated user

Kublr - kubectl OIDC Login - Diagram

Installing kubelogin

Install kubelogin accoding to the instructions.

Krew kubectl plugin manager is probably the easiest installation method:

kubectl krew install oidc-login

Aleternatively, kubelogin can be installed as follows:

  1. Download kubelogin binary.
  2. Rename to kubectl-oidc_login (note the difference between dash and underscore).
  3. Move the binary to any directory on the binary path.
  4. Test that the new command works by running kubectl oidc-login

Instructions

  1. Log into Kublr.

  2. Navigate to your cluster page.

  3. Use the CLUSTER tab.

  4. Find the CLI field, do one of the following:

    • Click Download Admin Cube Config File - this kubeconfig file contains configuration for the direct access to the cluster API with cluster-admin permission.

      This file is only available for download to Kublr users with admin permissions to the cluster.

      This kubeconfig file contains critical security information and should be handled and disctibuted (if necessary) with care.

    • Click Download User Cube Config File - this kubeconfig file contains configuration for Kublr-proxied OIDC-authenticated access to the target custer.

      This file does not contain any critical security information and can be distributed to any users, as this file configures kubectl for client-side OIDC authentication in Kublr OIDC identity provider.

    Note The “Admin” version of config will only be availablbe if you have the administator permissions.

    Cluster - CLI

  5. Place the downloaded kubeconfig file into an appropriate folder or configure KUBECONFIG environment variable to set upl the local kubectl as documented.

  6. Run kubectl. In your browser, the Kublr authorization window will be displayed.

  7. Use your Kublr login and password or follow the configured SSO authentication process.

    OIDC - Sign-In Window

  8. Click SIGN IN.

    In your browser, the OK message is displayed. You are now logged into your cluster via kubectl and can manage it.