Code module: OmniAuth & LDAP

OmniAuth Configuration

The spec.appConfig.omniauth section allows configuring external authentication providers in Deckhouse Code. OIDC, SAML, GitHub, GitLab, and other providers are supported.

Parameters

Provider Configuration

Each provider in the providers list is described by the following fields:

Fields for openid_connect:

Example:

args:
  name: openid_connect
  scope: ["openid", "profile", "email"]
  response_type: "code"
  issuer: "https://dex.example.com"
  discovery: true
  client_auth_method: "query"
  client_options:
    identifier: "<client-id>"
    secret: "<client-secret>"
    redirect_uri: "https://code.example.com/users/auth/openid_connect/callback"

OpenID Connect (OIDC)

Setting up authentication via Deckhouse (Dex)

1. Configure DexClient:

   apiVersion: deckhouse.io/v1
   kind: DexClient
   metadata:
     name: myname
     namespace: mynamespace
   spec:
     redirectURIs:
       - https://code.example.com/users/auth/openid_connect/callback
     allowedGroups:
       - Everyone
       - admins

2. Retrieve the DexClient secret:

   kubectl -n mynamespace get secret dex-client-myname -o jsonpath='{.data.clientSecret}' | base64 -d

3. Add the provider to CodeInstance:

   spec:
     appConfig:
       omniauth:
         enabled: true
         allowSingleSignOn:
           - openid_connect
         blockAutoCreatedUsers: false
         providers:
           - name: openid_connect
             label: "Deckhouse"
             args:
               name: openid_connect
               scope: ["openid", "profile", "email"]
               response_type: "code"
               issuer: "https://dex.example.com"
               discovery: true
               client_auth_method: "query"
               client_options:
                 identifier: "dex-client-myname@mynamespace"
                 secret: "<clientSecret>"
                 redirect_uri: "https://code.example.com/users/auth/openid_connect/callback"

4. Wait for changes to be applied by the operator.

SAML

For SAML integration, the following new parameters have been added:

• allowed_groups: An array of groups permitted to log in. Users who do not belong to these groups will be blocked and unable to log in.Default: null (allows all groups).
• admin_groups: An array of groups permitted to log in as administrators. Users belonging to these groups will be granted an admin role.Default: null (no groups are granted admin privileges).
• groups_attribute: The attribute name used to retrieve user groups. Default: 'Groups'.

Example Configuration

Section is under spec.appConfig.omniauth.

providers:
  - name: 'saml'
    allowed_groups:
      - 'gitlab'
    admin_groups:
      - 'admin'
    groups_attribute: 'gitlab_group'

Note: for oidc and SAML If a user belongs to admin_groups but is not present in allowed_groups, they will not be able to log in. In such cases, admin_groups will not be considered, and the user will not be granted administrative privileges.

LDAP Synchronization

Performs synchronization of users, groups, and group access rights with the LDAP server. By default, it happens once per hour.

You can configure the synchronization schedule via cronJobs param (at spec.appConfig. section):

cronJobs:
  ldapSyncWorker:
    cron: "0 * * * *"

LDAP Server-Side Limits

During synchronization, queries are made for all users and groups specified in the configuration file. The synchronization task automatically uses pagination if needed. However, if the LDAP server has a limit on the maximum number of records returned, it may lead to unexpected user access being blocked or removed.

Example LDAP Provider Configuration

Section is located under spec.appConfig.ldap.servers

main:
  label: ldap
  host: 127.0.0.1
  port: 3389
  bindDn: 'uid=viewer,ou=People,dc=example,dc=com'
  base: 'ou=People,dc=example,dc=com'
  uid: 'cn'
  password: 'viewer123'
  syncName: true
  groupSync:
    createGroups: true
    base: 'ou=Groups,dc=example,dc=org'
    filter: '(objectClass=groupOfNames)'
    prefix:
      attribute: 'businessCategory'
      default: 'default-program'
    topLevelGroup: "LdapGroups"
    nameMask: "(?<=-)[A-z0-9\_]*$"
    owner: "root"
    roleMapping:
      - byName: '.*-project_manager-.*'
        gitlabRole: 'Maintainer'
      - byName: '.*-developer-.*'
        gitlabRole: 'Developer'
      - byName: '.*-participant-.*'
        gitlabRole: 'Reporter'

Group and Access Rights Synchronization

Creates GitLab groups and assigns user roles based on records retrieved from the LDAP server. Can be configured with the following parameters:

Required Parameters:

• groupSync.base — The base DN from which the search begins.

Optional Parameters:

• groupSync.createGroups — If true, groups will be created in Deckhouse Code.
• groupSync.filter — LDAP filter for groups.
• groupSync.scope — Search scope (0 — Base, 1 — SingleLevel, 2 — WholeSubtree).
• groupSync.prefix — Defines which attribute to use for the parent group name. If the attribute is missing, the default value is used.
• groupSync.topLevelGroup — The name of the top-level group to which all synchronized groups will be added.
• groupSync.nameMask — A regular expression to extract the group name from the cn attribute. The expression must not contain capturing groups. The result of applying the expression must be exactly the value used as the group name. For strict boundaries, use lookbehind and/or lookahead.
• groupSync.owner — The username to be added as the group owner (default is root).

roleMapping section

Assigns access rights to users based on the group name (cn):

• roleMapping.byName — A regular expression; if the group name matches, the corresponding gitlabRole is assigned to the user.
• roleMapping.gitlabRole — The Deckhouse Code role name (e.g., Guest, Reporter, Developer, Maintainer, Owner).

Deckhouse Code leverages basic roles from Gitlab

How group membership is defined

Group members are determined from the following group attributes. The value of each attribute is expected to be an array of user DNs:

• member
• uniquemember
• memberof
• memberuid
• submember

User Synchronization

Locks and unlocks users and updates their name and email based on data from the LDAP server.

Optional parameters:

syncName - if true, the user’s name will be updated from LDAP data

Username Transformation Rule:

If an LDAP username contains a dot (.) followed by a file extension that matches an entry in the defined extensions table, the dot (.) preceding the extension is automatically replaced with an underscore (_).

This transformation ensures compatibility with GitLab’s username requirements while preserving the original identity as much as possible.

Examples:

Ldap username: a.ivanov.ini

Gitlab username:a.ivanov_ini

Ldap username: a.k.ivanov

Gitlab username:a.k.ivanov

Ldap username: a.k.ivanov.ini

Gitlab username:a.k.ivanov_ini

Ldap username: a.ini.ivanov

Gitlab username:a.ini.ivanov

Troubleshooting synchronization

If a previous synchronization job did not complete correctly, Redis may retain a record indicating the job is still running. This prevents a new job from starting because concurrency is set to 1.

To fix perform following steps:

1. Connect to Redis using the databases specified in config/redis.shared_state.yml and config/redis.queues.yml.
2. Delete the following key: sidekiq:concurrency_limit:throttled_jobs:{ldap/sync_worker} by executing:

• keys *ldap* - makes sures the key exists
• del "sidekiq:concurrency_limit:throttled_jobs:{ldap/sync_worker}" - deletes the key