This module sets up a unified authentication system integrated with Kubernetes and Web interfaces used in other modules (Grafana, Dashboard, etc.).

It consists of the following components:

  • dex — is a federated OpenID Connect provider that acts as an identity service for static users and can be linked to one or more ID providers (e.g., SAML providers, GitHub, and Gitlab);
  • kubeconfig-generator (in fact, dex-k8s-authenticator) — is a helper web application that (being authorized with dex) generates kubectl commands for creating and modifying a kubeconfig;
  • dex-authenticator (in fact, oauth2-proxy) — is an application that gets nginx ingress (auth_request) requests and authenticates them with dex.

Static users are managed using the User Custom Resource. It contains all the user-related data, including the password.

The following external authentication protocols/providers are supported:

  • Github
  • Gitlab
  • BitBucket Cloud
  • Crowd
  • LDAP
  • OIDC

You can use several external authentication providers simultaneously.

Integration features

Integration with Kubernetes and Deckhouse

The module generates control-plane-manager settings (based on the Kubernetes and Deckhouse versions).

Thus, one of these modules configures the kube-apiserver so that it becomes the dex OIDC client. Several other Deckhouse modules will also be configured to integrate with dex, including:

Authenticating to the Kubernetes API using a login and password

Currently, login and password-based authentication to the Kubernetes API is only available for the Crowd provider. Support for this feature for static users and LDAP-enabled providers is expected in the near future.

Integration with applications

To drive authentication for any web application, you only need to create a DexAuthenticator resource in the necessary namespace and add several annotations to the Ingress resource. After that, you can:

  • limit the list of groups that are allowed to connect;
  • limit the list of addresses for which authentication is allowed.

The application that supports OIDC authentication can be integrated into the unified authentication process. To do this, create a DexClient resource in the appropriate Kubernetes namespace. Next, a secret with the data to connect to the dex over OIDC will be created in this namespace.

Such integration provides the following opportunities:

  • the ability to limit the list of groups that are allowed to connect;
  • the ability to set a list of trusted clients whose OIDC tokens can be trusted (trustedPeers).

Web interface for generating ready-to-use kubeconfig files

The module can automatically generate a configuration file for kubectl or other Kubernetes utilities. The kubeconfig generator’s web interface provides to the authenticated user a set of kubectl commands for cluster management. Just copy/paste them into the console to use kubectl.

The kubeconfig authentication mechanism uses an OIDC token. An OIDC session can be extended automatically if the authentication provider used by dex supports session extension. For this, a refresh token is provided in kubeconfig.

Additionally, you can configure multiple kube-apiserver addresses and set a CA for each of them. It might come in handy if, for example, access takes place directly and over VPN.

Exposing the Kubernetes API using Ingress

As you know, kube-apiserver with no additional settings provided is only reachable from within the internal cluster network by default. This module solves the problem of effortless and secure access to the API from outside the cluster. In doing so, it exposes apiserver on the service domain (for more information, see the service domain template in global).

The following parameters can be specified when configuring:

  • a list of network addresses for which the connection is allowed;
  • a list of groups that are allowed to access apiserver;
  • an Ingress controller to use for authentication.

A dedicated CA will be generated by default, and the kubeconfig generator will be configured automatically.

Flant-made extensions

The module makes use of a modified version of dex that contains the following updated and corrected functionality:

  • support for groups for static users and the bitbucketCloud provider;
  • ability to pass the group parameter to clients;
  • support for the obsolete tokens mechanism (it prevents race conditions when the OIDC client renews the token).

High availability mode

The module also supports the highAvailability mode. When this mode is enabled, all components responding to the auth requests are deployed with the redundancy required to operate continuously without failure. Thus, the user authentication sessions are kept alive even if any of the authenticator instances fail.