Available in editions: Open/CE, BE, SE, SE+, Ultimate/EE, Core
Included in extensions: Billing
The module lifecycle stage: General Availability
The module sets up a unified authentication system integrated with Kubernetes and Web interfaces used in other modules (Grafana, Dashboard, etc.).
Main features
The module provides the following features:
- Single sign-on to the web interfaces of Deckhouse Platform (DP) modules and to the Kubernetes API through Dex
- Sign-in through external providers: GitHub, GitLab, Bitbucket Cloud, Atlassian Crowd, LDAP (with Kerberos SSO), OIDC and SAML 2.0
- Static users and groups with a password policy, account lockout and two-factor authentication
- Authentication for any web application in the cluster with DexAuthenticator, and OAuth2 clients for applications that support OIDC (DexClient)
- Kubeconfig generation in the Deckhouse web UI for access with
kubectland OIDC tokens - Basic authentication to the Kubernetes API through one Crowd, OIDC or LDAP provider
Components
The module 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);
dex-authenticator(based on oauth2-proxy) authenticates requests to an application published through an Ingress or, with thealbmodule, through Gateway API.
Management of static users is performed using the User and Group resources:
- The User object stores user information, including the email address and a password hash (the plain-text password is not stored);
- The Group object defines a list of users grouped together for easier access management.
User management operations — creating and deleting users, managing groups, resetting passwords, resetting 2FA, and locking/unlocking — can be performed via the CLI using the d8 iam command group or via the UserOperation resource. The UserOperation resource is single-use and is automatically deleted after retention.userOperations (24 hours by default).
The following external authentication protocols/providers are supported:
- GitHub;
- GitLab;
- BitBucket Cloud;
- Crowd;
- LDAP;
- OIDC;
- SAML 2.0.
You can use several external authentication providers simultaneously.
Integration features
OIDC authentication in kube-apiserver is configured automatically by the control-plane-manager module. For details, see Configuring kube-apiserver.
When the module is enabled, the web interfaces of DP modules authenticate users through Dex instead of HTTP Basic Auth.
Basic authentication for the Kubernetes API requests
Basic authentication for Kubernetes API requests is available for the Crowd, OIDC and LDAP providers (the enableBasicAuth parameter in the crowd, oidc or ldap section). It can be enabled for only one provider in the cluster. For a Crowd or OIDC provider, Basic Authentication bypasses the identity limits of the provider, so only a SuperAdmin can enable it.
You can also connect to the Kubernetes API via other supported external providers.
Application integration
To add authentication to any web application in the cluster, create a DexAuthenticator in the namespace of the application and add the authentication annotations to its Ingress or HTTPRoute. DexAuthenticator can limit the groups and emails that are allowed to sign in and the networks from which users can authenticate.
If the application supports OIDC itself, create a DexClient in its namespace instead. The module registers an OAuth2 client in Dex and creates the dex-client-<NAME> Secret with the client secret in the same namespace. DexClient can limit the groups and emails that are allowed to sign in and list the clients whose tokens the application trusts (trustedPeers).
Generating kubeconfig files
After signing in, a user can generate a kubeconfig for kubectl and other Kubernetes tools in the Deckhouse web UI.
The kubeconfig uses an OIDC token. If the authentication provider supports session extension, the kubeconfig also contains a refresh token, and the session is extended automatically. If the provider reports during the extension that the user no longer exists or has lost access, Dex refuses the refresh token with the invalid_grant error, and the user has to sign in again.
The kubeconfigGenerator parameter adds other ways to reach the API server, each with its own address and CA certificate, for example, for access through a bastion host or a VPN.
Additional Dex capabilities
The module ships Dex with additional capabilities:
- Groups for static users (the Group object)
- Two-factor authentication (2FA) for local users and the users of LDAP and Crowd providers (the
twoFactorparameter) - A password policy for static users: complexity, password history, rotation and lockout after failed sign-in attempts (the
passwordPolicyparameter) - A forced password change at the next sign-in after an administrator resets the password
- Lockout after failed sign-in attempts for LDAP and Atlassian Crowd users (the
passwordPolicy.lockout.applyToConnectorsparameter) - Per-IP rate limiting of failed sign-in attempts (the
rateLimitparameter) - Locking and unlocking users of any provider with the UserOperation object, also without a password policy
- Lists of allowed users and groups in DexClient and DexAuthenticator that Dex checks at sign-in and at every refresh-token request
- Limits on the identities a provider may assert (the
spec.allowedIdentitiesparameter of DexProvider) - Kerberos (SPNEGO) sign-in through the LDAP provider without the password form, with tickets from the
Authorization: Negotiateheader validated by the service keytab - Refresh tokens for the SAML provider
- A custom CA certificate for the GitLab provider (the
gitlab.rootCADataparameter)
High availability mode
In high availability mode (highAvailability), Dex and the other module components run in several replicas, so sign-in keeps working if one pod fails. DexAuthenticator follows the same setting unless its own spec.highAvailability is set.
Third-party components
List of third-party software used in the user-authn module:
-
Dex 2.46.0
License: Apache License 2.0
A Federated OpenID Connect Provider with pluggable connectors.
-
OAuth2 Proxy 7.15.5
License: MIT License
A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group.