The user-authn module: usage

An example of the module configuration

The example shows the configuration of the user-authn module in the Deckhouse Kubernetes Platform.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 2
  enabled: true
  settings:
    kubeconfigGenerator:
    - id: direct
      masterURI: https://159.89.5.247:6443
      description: "Direct access to kubernetes API"
    publishAPI:
      enabled: true

Configuring a provider

GitHub

The example shows the provider’s settings for integration with GitHub.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: github
spec:
  type: Github
  displayName: My Company Github
  # Optional: disable the provider without deleting CR
  # enabled: false
  github:
    clientID: plainstring
    clientSecret: plainstring

In your GitHub organization, create a new application:

To do this, go to Settings -> Developer settings -> OAuth Aps -> Register a new OAuth application and specify the https://dex.<modules.publicDomainTemplate>/callback address as the Authorization callback URL.

Paste the generated Client ID and Client Secret into the DexProvider custom resource.

If the GitHub organization is managed by the client, go to Settings -> Applications -> Authorized OAuth Apps -> <name of created OAuth App> and request confirmation by clicking on Send Request. Then ask the client to confirm the request that will be sent to him by email.

GitLab

The example shows the provider’s settings for integration with GitLab.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: gitlab
spec:
  type: Gitlab
  displayName: Dedicated GitLab
  gitlab:
    baseURL: https://gitlab.example.com
    clientID: plainstring
    clientSecret: plainstring
    groups:
    - administrators
    - users

Create a new application in the GitLab project.

To do this, you need to:

• self-hosted: go to Admin area -> Application -> New application and specify the https://dex.<modules.publicDomainTemplate>/callback address as the Redirect URI (Callback URL) and set scopes read_user, openid;
• cloud gitlab.com: under the main project account, go to User Settings -> Application -> New application and specify the https://dex.<modules.publicDomainTemplate>/callback address as the Redirect URI (Callback URL); also, don’t forget to set scopes read_user, openid;
• (for GitLab version starting with 16) enable the Trusted/Trusted applications are automatically authorized on GitLab OAuth flow checkbox when creating an application.

Paste the generated Application ID and Secret into the DexProvider custom resource.

Atlassian Crowd

The example shows the provider’s settings for integration with Atlassian Crowd.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: crowd
spec:
  type: Crowd
  displayName: Crowd
  crowd:
    baseURL: https://crowd.example.com/crowd
    clientID: plainstring
    clientSecret: plainstring
    enableBasicAuth: true
    groups:
    - administrators
    - users

Create a new Generic application in the corresponding Atlassian Crowd project.

To do this, go to Applications -> Add application.

Paste the generated Application Name and Password into the DexProvider custom resource.

CROWD groups are specified in the lowercase format for the custom resource DexProvider.

Bitbucket Cloud

The example shows the provider’s settings for integration with Bitbucket Cloud.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: bitbucket
spec:
  type: BitbucketCloud
  displayName: Bitbucket
  bitbucketCloud:
    clientID: plainstring
    clientSecret: plainstring
    includeTeamGroups: true
    teams:
    - administrators
    - users

Create a new OAuth consumer in the Bitbucket’s team menu.

To do this, go to Settings -> OAuth consumers -> New application and specify the https://dex.<modules.publicDomainTemplate>/callback address as the Callback URL. Also, allow access for Account: Read and Workspace membership: Read.

Paste the generated Key and Secret into the DexProvider custom resource.

OIDC (OpenID Connect)

Authentication through the OIDC provider requires registering a client (or “creating an application”). Please refer to the provider’s documentation on how to do it (e.g., Okta, Keycloak, Gluu).

Paste the generated clientID and clientSecret into the DexProvider custom resource.

Keycloak

After selecting a realm to configure, adding a user in the Users section, and creating a client in the Clients section with authentication enabled, which is required to generate the clientSecret, you need to perform the following steps:

• Create a scope named groups in the Client scopes section and assign it the predefined mapping groups. (“Client scopes” → “Client scope details” → “Mappers” → “Add predefined mappers”)
• In the previously created client, add this scope in the Client scopes tab (“Clients” → “Client details” → “Client Scopes” → “Add client scope”).
• In the “Valid redirect URIs”, “Valid post logout redirect URIs”, and “Web origins” fields of the client configuration, specify https://dex.<publicDomainTemplate>/*, where publicDomainTemplate is a value of the parameter in the global module config.

The example shows the provider’s settings for integration with Keycloak.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: keycloak
spec:
  type: OIDC
  displayName: My Company Keycloak
  oidc:
    issuer: https://keycloak.my-company.com/realms/myrealm # Use the name of your realm
    clientID: plainstring
    clientSecret: plainstring
    insecureSkipEmailVerified: true    
    getUserInfo: true
    scopes:
      - openid
      - profile
      - email
      - groups

If email verification is not enabled in Keycloak, to properly use it as an identity provider, adjust the Client Scopes settings in one of the following ways:

• Delete the Email verified mapping (“Client Scopes” → “Email” → “Mappers”). This is required for proper processing of the insecureSkipEmailVerified field when it’s set to true and for correct permission assignment to users with unverified emails.

• If you can’t modify or delete the Email verified mapping, create a new Client Scope named email_dkp (or any other name) and add two mappings:

  • email: “Client Scopes” → email_dkp → “Add mapper” → “From predefined mappers” → email.
  • email verified: “Client Scopes” → email_dkp → “Add mapper” → “By configuration” → “Hardcoded claim”. Specify the following fields:
    • “Name”: email verified
    • “Token Claim Name”: emailVerified
    • “Claim value”: true
    • “Claim JSON Type”: boolean

  After that, in the client registered for the DKP cluster in “Clients”, change Client scopes from email to email_dkp.

  In the DexProvider resource, specify insecureSkipEmailVerified: true and in the .spec.oidc.scopes field, change the Client Scope name to email_dkp following the example:

      scopes:
        - openid
        - profile
        - email_dkp
        - groups
  

Okta

The example shows the provider’s settings for integration with Okta.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: okta
spec:
  type: OIDC
  displayName: My Company Okta
  oidc:
    issuer: https://my-company.okta.com
    clientID: plainstring
    clientSecret: plainstring
    insecureSkipEmailVerified: true
    getUserInfo: true

Blitz Identity Provider

Note that you must specify a URL to redirect the user after authorization when registering the application with the Blitz Identity Provider. When using DexProvider, you must specify https://dex.<publicDomainTemplate>/, where publicDomainTemplate is the cluster’s DNS name template as defined in the global module.

The example below shows the provider settings for integration with Blitz Identity Provider.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: blitz
spec:
  displayName: Blitz Identity Provider
  oidc:
    basicAuthUnsupported: false
    claimMapping:
      email: email
      groups: your_claim # Claim for getting user groups, configured on the Blitz
    clientID: clientID
    clientSecret: clientSecret
    getUserInfo: true
    insecureSkipEmailVerified: true # Set to true if there is no need to verify the user's email
    insecureSkipVerify: false
    issuer: https://yourdomain.idblitz.ru/blitz
    promptType: consent 
    scopes:
    - profile
    - openid
    userIDKey: sub
    userNameKey: email
  type: OIDC

For the application logout to work correctly (the token being revoked so that re-authorization is required), set login as the value of the ‘promptType` parameter.

To ensure granular user access to applications, you have to:

• Add the allowedUserGroups parameter to the ModuleConfig of the target application.
• Add the user to the groups (group names should be the same for Blitz and Deckhouse).

Below is an example for prometheus:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  settings:
    auth:
      allowedUserGroups:
        - adm-grafana-access
        - grafana-access

LDAP

The example shows the provider’s settings for integration with Active Directory.

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    insecureSkipVerify: true

    bindDN: cn=Administrator,cn=users,dc=example,dc=com
    bindPW: admin0!
    
    usernamePrompt: Email Address

    enableBasicAuth: true

    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=person)"
      username: userPrincipalName
      idAttr: DN
      emailAttr: userPrincipalName
      nameAttr: cn

    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      filter: "(objectClass=group)"
      userMatchers:
      - userAttr: DN
        groupAttr: member
      nameAttr: cn

Configuring Basic Authentication

To enable Basic Authentication for the Kubernetes API using LDAP credentials:

1. Ensure that the publishAPI parameter is enabled in the user-authn module configuration.
2. Set enableBasicAuth: true in your LDAP DexProvider resource.

Warning. Only one provider in the cluster can have enableBasicAuth enabled.

After configuration, users can access the Kubernetes API via kubectl, using their LDAP username and password.

Example kubeconfig for the user:

apiVersion: v1
kind: Config
clusters:
- name: my-cluster
  cluster:
    server: https://api.example.com
    # Path to CA certificate or insecure-skip-tls-verify: true
    certificate-authority: /path/to/ca.crt
users:
- name: ldap-user
  user:
    username: janedoe@example.com
    password: userpassword
contexts:
- name: default
  context:
    cluster: my-cluster
    user: ldap-user
current-context: default

Kerberos (SPNEGO) SSO for LDAP

Dex supports passwordless Kerberos (SPNEGO) flow for the LDAP connector. When enabled, a browser that trusts the Dex host will send Authorization: Negotiate … and Dex will validate the Kerberos ticket using a service keytab, skip the login form, map the Kerberos principal to an LDAP username, query groups, and complete the OIDC flow.

Minimal example extending the LDAP provider spec:

apiVersion: deckhouse.io/v1
kind: DexProvider
metadata:
  name: active-directory
spec:
  type: LDAP
  displayName: Active Directory
  ldap:
    host: ad.example.com:636
    bindDN: cn=Administrator,cn=users,dc=example,dc=com
    bindPW: admin0!
    userSearch:
      baseDN: cn=Users,dc=example,dc=com
      username: sAMAccountName
      idAttr: uid
      emailAttr: mail
      nameAttr: cn
    groupSearch:
      baseDN: cn=Users,dc=example,dc=com
      nameAttr: cn
      userMatchers:
      - userAttr: uid
        groupAttr: memberUid
    kerberos:
      enabled: true
      keytabSecretName: dex-kerberos-keytab   # Secret in d8-user-authn with key 'krb5.keytab'
      expectedRealm: EXAMPLE.COM              # optional, case-insensitive match
      usernameFromPrincipal: sAMAccountName   # localpart|sAMAccountName|userPrincipalName
      fallbackToPassword: false               # default false; if true, render form when header missing/invalid

Notes:

• The Secret dex-kerberos-keytab must exist in the d8-user-authn namespace and have a data key named exactly krb5.keytab.
• A single Dex Pod can serve multiple LDAP+Kerberos providers. Each provider mounts its own keytab; a shared krb5.conf is not required (Dex validates tickets offline using the keytab). To configure authentication, create a read-only user (service account) in LDAP.

Specify the generated user path and password in the bindDN and bindPW fields of the DexProvider custom resource. Enter the password into the bindPW in plain-text format (unencrypted). Strategies involving the passing of hashed passwords are not supported.

You can omit these settings if anonymous read access is configured for LDAP.

Configuring the OAuth2 client in Dex for connecting an application

This configuration is suitable for applications that can independently perform oauth2 authentication without using an oauth2 proxy. The DexClient custom resource enables applications to use dex.

apiVersion: deckhouse.io/v1
kind: DexClient
metadata:
  name: myname
  namespace: mynamespace
spec:
  redirectURIs:
  - https://app.example.com/callback
  - https://app.example.com/callback-reserve
  allowedGroups:
  - Everyone
  - admins
  trustedPeers:
  - opendistro-sibling

After the DexClient custom resource is created, Dex will register a client with a dex-client-myname@mynamespace ID (clientID).

The client access password (clientSecret) will be stored in the secret object:

apiVersion: v1
kind: Secret
metadata:
  name: dex-client-myname
  namespace: mynamespace
type: Opaque
data:
  clientSecret: c2VjcmV0

Local Authentication

Local authentication provides user verification and access management with support for configurable password policies, two-factor authentication (2FA), and group management.
The implementation complies with OWASP recommendations, ensuring reliable protection of access to the cluster and applications without requiring integration with external authentication systems.

Creating a user

Create a password and enter its hash encoded in base64 in the password field. The email address must be in lowercase.

Use the command below to calculate the password hash:

echo -n '3xAmpl3Pa$$wo#d' | htpasswd -BinC 10 "" | cut -d: -f2 | tr -d '\n' | base64 -w0; echo

Alternatively, you can use the online service to calculate the password hash.

Note that in the below example the ttl parameter is set.

apiVersion: deckhouse.io/v1
kind: User
metadata:
  name: admin
spec:
  email: admin@yourcompany.com
  # echo -n '3xAmpl3Pa$$wo#d' | htpasswd -BinC 10 "" | cut -d: -f2 | tr -d '\n' | base64 -w0; echo
  password: 'JDJ5JDEwJGRNWGVGUVBkdUdYYVMyWDFPcGdZdk9HSy81LkdsNm5sdU9mUkhnNWlQdDhuSlh6SzhpeS5H'
  ttl: 24h

Adding a user to a group

Users can be grouped to manage access rights. Example manifest of the Group resource for a group:

apiVersion: deckhouse.io/v1alpha1
kind: Group
metadata:
  name: admins
spec:
  name: admins
  members:
    - kind: User
      name: admin

Where members is a list of users belonging to the group.

Password policy

Password policy settings allow controlling password complexity, rotation, and user lockout:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 2
  enabled: true
  settings:
    passwordPolicy:
      complexityLevel: Fair
      passwordHistoryLimit: 10
      lockout:
        lockDuration: 15m
        maxAttempts: 3
      rotation:
        interval: "30d"

Field description:

• complexityLevel: Password complexity level.
• passwordHistoryLimit: Number of previous passwords stored in the system to prevent their reuse.
• lockout: Lockout settings after exceeding the limit of failed login attempts:
  • lockout.maxAttempts: Limit of allowed failed login attempts.
  • lockout.lockDuration: User lockout duration.
• rotation: Password rotation settings:
  • rotation.interval: Period for mandatory password change.

Two-factor authentication (2FA)

2FA increases security by requiring a code from a TOTP authenticator application (for example, Google Authenticator) during login.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 2
  enabled: true
  settings:
    staticUsers2FA:
      enabled: true
      issuerName: "awesome-app"

Field description:

• enabled: Enables or disables 2FA for all static users.
• issuerName: Name displayed in the authenticator application when adding an account.

Assigning permissions to a user or group

For permission configuration, parameters of the custom resource ClusterAuthorizationRule are used.