Skip to content

Latest commit

 

History

History
89 lines (54 loc) · 6.77 KB

using-an-OIDC-provider.md

File metadata and controls

89 lines (54 loc) · 6.77 KB

Using an OAuth2/OIDC provider in Kubeapps

Table of Contents

  1. Introduction
  2. Pre-requisites
  3. Identity providers (IdP)
  4. OIDC provider configuration
    1. OIDC parameters
    2. Redirection
  5. Troubleshooting

Introduction

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 requires you being able 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). If you are unable to configure your cluster's API server flags for OIDC, then it is recommended that you have a look at the Pinniped project, which enables dynamic OIDC authentication configuration of clusters.

This tutorial describes how to use an existing OAuth2 provider, including OIDC, to authenticate users within Kubeapps.

Pre-requisites

Identity Providers (IdP)

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:

OIDC provider configuration

Kubeapps uses OAuth2 Proxy to handle the OIDC authentication flow (exchange the credentials, retrieve the token, redirect back to Kubeapps, etc.)

Configure parameters

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 be oidc, 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:

Configure redirection

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.

Deploying an auth proxy to access Kubeapps

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.

Troubleshooting

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.