The user-authn module implements a unified authentication system integrated with Kubernetes and the web interfaces used by modules of Deckhouse Platform (DP), such as the console module.
For more details about module configuration and usage examples, refer to the corresponding documentation section.
Module architecture
The following simplifications are made in the diagram:
- The diagram shows containers in different pods interacting directly with each other. In reality, they communicate via the corresponding Kubernetes Services (internal load balancers). Service names are omitted if they are obvious from the diagram context. Otherwise, the Service name is shown above the arrow.
- Pods may run multiple replicas. However, each pod is shown as a single replica in the diagram.
In DP, two authentication schemes are used for platform services and user applications:
- Using dex-authenticator
- Using the Dex client
The architecture of the user-authn module at Level 2 of the C4 model and its interactions with other DP components are shown in the following diagrams.
Using dex-authenticator:
For simplicity, the following diagrams show only the components and their interactions that distinguish these diagrams from the variant using dex-authenticator.
Using the Dex client:
When connecting to the Kubernetes API using d8, kubectl or other Kubernetes clients with a generated kubeconfig, a separate authentication schemes are used:
- Token authentication. It is described in detail in the corresponding documentation section.
- Basic authentication. An example of configuring basic authentication using an LDAP provider is described in the module documentation section.
Using a generated kubeconfig and a token authentication:
Using a generated kubeconfig and a basic authentication:
Module components
The module consists of the following components:
-
Dex: Federated OpenID Connect provider that supports static users and integration with external authentication providers such as SAML, GitLab, or GitHub. The module uses a modified version of Dex to support:
- Groups for static user accounts.
- Two-factor authentication (2FA).
- Password policies.
- Forced password change.
- Kerberos (SPNEGO) support for the LDAP connector. When enabled, Dex accepts
Authorization: Negotiatetickets, validates them with a service keytab, and completes the login without rendering the password form, etc.
For actual list of Dex modifications, refer to the module repository.
It consists of the following containers:
- dex: Main container implementing Dex functions.
- kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC that provides secure access to provider metrics. It is an open source project.
-
Dex-authenticator: Middleware service used to authenticate requests to applications through the DP cluster authentication service.
When the Ingress controller is configured accordingly (using the NGINX
auth_requestmodule), requests are first forwarded to dex-authenticator for authentication.It consists of the following containers:
- dex-authenticator: Main container of the service.
- redis: Sidecar container with a Redis database used for temporary storage of ID tokens and fast access to them (since the database resides in memory).
- self-signed-generator: Init container that generates a self-signed certificate when the pod starts.
-
User-authn-controller: A controller that consists of a single user-authn-controller container and performing following operations:
-
Manages module custom resources:
- Group: A resource that describes user group.
- User: A resource that describes static user.
- UserAccount: A resource that describes view of Dex Password, OfflineSessions, and UserIdentity objects for the Deckhouse web UI.
- UserOperation: A resource that describes an operation to be applied to a user (password reset, forced password change, 2FA reset, lock/unlock, logout).
- DexProviderCheck: A resource that describes a connectivity check for the specific DexProvider. The check verifies that the provider exists, is enabled, Dex is reachable, and the provider endpoint is reachable. It does not perform a full user authentication flow.
- Deletes expired Users (users whose
status.expireAtfield is in the past). - Checks periodically an availability of configured external authentication providers (using DexProviderCheck custom resources).
- Finds out conflicting TLS-certificates in external LDAP provider configuration settings and exports the corresponding metric.
- Revokes the sessions of a user on a lock, a password or 2FA reset, a logout and a user deletion: raises the generation of the user’s Dex account, writes a Dex Revocation object, and deletes the user’s Dex AuthSession and RefreshToken objects.
- Serves the revocations to dex-authenticator over HTTPS (the
revocation-feedService), so that dex-authenticator ends the revoked sessions within seconds. - Keeps the
kubernetesDex client (OAuth2Client) and itstrustedPeers: the DexAuthenticators and DexClients allowed access to Kubernetes, and the static clients of the module configuration.
User-authn-controller uses
dex.coreos.comAPI group custom resources (Password, OfflineSessions, UserIdentity, and RefreshToken used by Dex as a storage) as a backend to manage module custom resources. -
-
Dexclient-controller: A controller that consists of a single dexclient-controller container (the image of user-authn-controller) and keeps the credentials of every DexClient: the
dex-client-<name>Secret in the namespace of the DexClient and its Dex clients (OAuth2Client). It is the only component of the module that can write Secrets in other namespaces, and it serves nothing on the network but health and metrics. -
User-api: A component that implements self-service operations for the user who is signed in to the DKP web interface: signing out on all devices and changing the password of a local account. It accepts only the ID tokens of the DKP web interface and does not require platform administrator rights. For each operation, the component creates a UserOperation custom resource of the
LogoutorRequirePasswordChangetype, which is processed by the user-authn-controller component. A ValidatingAdmissionPolicy allows user-api to create only these operations.It consists of the following containers:
- user-api: Main container of the service.
-
Basic-auth-proxy: An optional component consisting of a single proxy container, which is launched when basic authentication is enabled in the settings of one of an external providers. When connecting to the Kubernetes API, the basic-auth-proxy component performs basic user authentication (through Dex for an LDAP provider, directly with the provider for a Crowd or OIDC provider), caches credentials validation results, and proxies authenticated requests to the Kubernetes API.
Module interactions
The module interacts with the following components:
- External authentication providers.
-
Kube-apiserver:
- Manages module custom resources.
- Authorizes requests for metrics.
The following external components interact with the module:
-
Ingress controller: Forwards authentication requests to dex-authenticator for DP platform services and user applications.
-
User applications: Can authenticate directly with dex (without dex-authenticator) if an OAuth2 client is configured in Dex for the application. For more details about configuring a Dex client, refer to the
user-authnmodule documentation. -
Kube-apiserver: Queries dex when processing Kubernetes API requests made using a kubeconfig file:
- kube-apiserver reads the OIDC provider configuration (Dex in this case) to obtain the
issuerand the parameters required to validate tokens via the JWKS endpoint. In Kubernetes 1.30 and later, it reads it through the Dex Service inside the cluster. - When receiving a request with an ID token, kube-apiserver verifies its signature using the keys obtained from the JWKS endpoint, then it compares token claims against the server configuration.
More details about connecting to the Kubernetes API using a generated kubeconfig can be found in the corresponding documentation page.
- kube-apiserver reads the OIDC provider configuration (Dex in this case) to obtain the
- Prometheus-main: Collects metrics from the dex provider.
- Deckhouse web UI: Forwards user requests for password reset.