OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol that allows clients to verify the identity of a user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the user.
In Kubernetes, one of the authentication strategies for incoming requests to the API server is using OpenID Connect tokens. The cluster can be configured to trust an external OIDC provider so that authenticated requests can be matched with defined RBAC. Additionally, some managed Kubernetes environments enable authenticating via plain OAuth2.
However, for Kubernetes to be able to use OIDC-based authentication it is required to enable certain flags in the API server, which is not always possible on certain environments (such as managed Kubernetes distributions by a cloud provider). To work around this limitation, it is recommended having a look at the Pinniped project.
This tutorial describes how to use an existing OAuth2 provider, including OIDC, to authenticate users within Kubeapps.
-
A Kubernetes cluster that is properly configured to use an OIDC Identity Provider (IdP) to handle the authentication to your cluster.
-
Read more information about the Kubernetes API server's configuration options for OIDC. This allows the Kubernetes API server itself to trust tokens from the identity provider. Some hosted Kubernetes services are already configured to accept
access_tokens from their identity provider as bearer tokens (see GKE below). -
Alternatively, if you do not have access to configure your cluster's API server, you can install and configure Pinniped in your cluster to trust your identity provider and configure Kubeapps to proxy requests via Pinniped.
-
Any OIDC-compliant Identity Provider (IdP) that can be used in a Kubernetes cluster. The steps of this guide have been validated using the following providers:
- VMware Cloud Services: VMware Cloud Services as an OIDC provider.
- Azure Active Directory: Identity Provider that can be used for AKS.
- Google OpenID Connect: OAuth 2.0 for Google accounts.
- Dex: Open Source OIDC and OAuth 2.0 Provider with Pluggable Connectors.
- Keycloak: Open Source Identity and Access Management.
Kubeapps uses OAuth2 Proxy to handle the OIDC authentication flow (exchange the credentials, retrieve the token, redirect back to Kubeapps, etc.)
The minimum set of parameters to use an Identity Provider for Kubeapps are the following:
Client ID: Client ID of the IdP.Client Secret: (If configured) Secret used to validate the Client ID.Provider name(which can beoidc, in which case the OIDC Issuer URL is also required).Cookie secret: a 16, 24 or 32 byte base64 encoded seed string used to encrypt sensitive data (eg.echo "not-good-secret" | base64). More information on the OAuth2 Proxy documentation.
Note: More parameters may be necessary depending on the Identity Provider and the aimed configuration.
The following sections dive deep into each validated identity provider and describe how to locate the required configuration parameters:
When configuring the identity provider, you need to ensure that the redirect URL for your Kubeapps installation is configured, which is your Kubeapps URL with the absolute path /oauth2/callback. For example, if you are deploying Kubeapps with TLS on the domain my-kubeapps.example.com, then the redirect URL is https://my-kubeapps.example.com/oauth2/callback.
The main difference in the authentication is that instead of accessing the Kubeapps service, you are accessing an oauth2 proxy service that is in charge of authenticating users with the identity provider and injecting the required credentials in the requests to Kubeapps.
Read the OAuth2 Proxy Auth configuration page for detailed information.
There are a number of available solutions for this use-case, like keycloak-gatekeeper or oauth2_proxy.
The next sections explain how you can deploy this proxy either using the Kubeapps chart or manually:
Once the proxy is accessible, you will be redirected to the identity provider to authenticate. After successfully authenticating, you will be redirected to Kubeapps and be authenticated with your user's OIDC token.
If you find after configuring your OIDC/OAuth2 setup following the above instructions, that although you can successfully authenticate with your provider you are nonetheless unable to login to Kubeapps but instead see a 403 or 401 request in the browser's debugger, then you need to investigate why the Kubernetes cluster is not accepting your credential.
Visit the debugging auth failures when using OIDC page for more information.