In the Deckhouse Kubernetes Platform module the parameters are set in the CodeInstance resource, described on the Authentication and LDAP and Custom resources pages of the module documentation. What each parameter does is described in Overview; this page gives the section of the manifest it is written in.

OmniAuth

The general parameters are set in the spec.appConfig.omniauth section, and the providers are listed in its providers parameter.

OIDC configuration example

This configuration is set in the spec.appConfig.omniauth section:

providers:
  - name: 'openid_connect'   # Do not change this value.
    label: 'Keycloak'        # Sign-in button label.
    allowed_groups:
      - 'gitlab'
    admin_groups:
      - 'admin'
    auditor_groups:
      - 'audit'
    groups_attribute: 'gitlab_group'
    args:
      name: 'openid_connect'
      scope:
        - 'openid'
        - 'profile'
        - 'email'
      response_type: 'code'
      issuer: 'https://keycloak.example.com/realms/example'
      discovery: true
      client_auth_method: 'query'
      uid_field: 'preferred_username'
      send_scope_to_token_endpoint: false
      pkce: true
      client_options:
        identifier: '<client_id>'
        secret: '<client_secret>'
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'

SAML configuration example

This configuration is set in the spec.appConfig.omniauth section:

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

LDAP

The LDAP servers are described in the spec.appConfig.ldap section.

Synchronization interval

The interval is set by the cronJobs parameter of the spec.appConfig section:

cronJobs:
  ldap_sync_worker:
    cron: "0 * * * *"

LDAP provider configuration example

The configuration is defined in spec.appConfig.ldap:

main:
  label: ldap
  host: 127.0.0.1
  port: 3389
  bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
  base: 'ou=People,dc=example,dc=com'
  uid: 'cn'
  password: 'viewer123'
  sync_name: true
  group_sync: {
    create_groups: true,
    base: 'ou=Groups,dc=example,dc=org',
    filter: '(objectClass=groupOfNames)',
    prefix: {
      attribute: 'businessCategory',
      default: 'default-program',
    },
    top_level_group: "LdapGroups",
    name_mask: "(?<=-)[A-z0-9]*$",
    owner: "root",
    role_mapping: [
      { by_name: '.*-project_manager-.*', gitlab_role: 'maintainer' },
      { by_name: '.*-developer-.*', gitlab_role: 'developer' },
      { by_name: '.*-participant-.*', gitlab_role: 'reporter' }
    ]
  }

Multiple LDAP servers

The spec.appConfig.ldap section can describe several LDAP servers. Each server has its own connection parameters; the group_sync section with everything in it is taken into account only for the server under the main key (see Synchronization scope):

main:
  label: 'Head office'
  host: ldap-main.example.com
  base: 'ou=People,dc=example,dc=com'
  uid: 'cn'
  # Other connection parameters.
  group_sync: {
    base: 'ou=Groups,dc=example,dc=com',
    role_mapping: [
      { by_name: '.*-developer-.*', gitlab_role: 'developer' }
    ]
  }
contractors:
  label: 'Contractors'
  host: ldap-contractors.example.com
  base: 'ou=People,dc=contractors,dc=example,dc=com'
  uid: 'cn'
  # Other connection parameters.

Linking OIDC accounts to LDAP

Automatic linking of the OIDC account to the LDAP account is enabled in the spec.appConfig.omniauth section:

auto_link_ldap_user: true

LDAP as the source of truth

To allow users found in LDAP to sign in immediately and require administrator approval for everyone else, set the following parameters in the spec.appConfig section:

omniauth:
  auto_link_ldap_user: true
  # The user is not found in LDAP — the account is created blocked,
  # pending administrator approval.
  block_auto_created_users: true
ldap:
  main:
    # The user is found in LDAP — sign-in is allowed immediately.
    block_auto_created_users: false

Configuration example: signing in through OIDC with permissions from LDAP

The steps below describe a setup where users sign in through an OIDC provider (for example, Keycloak), while groups, memberships, and roles come from LDAP.

The setup includes the following steps:

  1. Configure the LDAP provider.
  2. Configure the OIDC provider and enable the LDAP integration.
  3. Verify the integration upon first login.
  4. Synchronize permissions.

Prerequisites

To set this up, you’ll need:

  • An OIDC provider.
  • An LDAP directory with the same users and with groups whose names allow determining the role.
  • An LDAP service account with read access to the directory (the bind_dn and password parameters).

The uid or email value in the OIDC provider must match the value of the corresponding attribute in LDAP, otherwise linking will not work (see How the LDAP account is found).

Configure the LDAP provider

Set up the configuration in spec.appConfig.ldap:

main:
  label: ldap
  host: ldap.example.com
  port: 3389
  bind_dn: 'uid=viewer,ou=People,dc=example,dc=com'
  password: 'viewer123'
  base: 'ou=People,dc=example,dc=com'
  uid: 'cn'
  sync_name: true
  # Ignore users blocked in the directory (optional).
  user_filter: '(!(nsAccountLock=TRUE))'
  # The user is found in LDAP — sign-in is allowed immediately.
  block_auto_created_users: false
  group_sync: {
    create_groups: true,
    base: 'ou=Groups,dc=example,dc=com',
    filter: '(objectClass=groupOfNames)',
    top_level_group: "LdapGroups",
    name_mask: "(?<=-)[A-z0-9]*$",
    owner: "root",
    role_mapping: [
      { by_name: '.*-maintainer-.*', gitlab_role: 'maintainer' },
      { by_name: '.*-developer-.*', gitlab_role: 'developer' },
      { by_name: '.*-participant-.*', gitlab_role: 'reporter' }
    ]
  }

Configure the OIDC provider and enable linking to LDAP

Set up the configuration in the spec.appConfig.omniauth section:

auto_link_ldap_user: true
providers:
  - name: 'openid_connect'   # Do not change this value.
    label: 'Keycloak'        # Sign-in button label.
    groups_attribute: 'gitlab_group'
    args:
      name: 'openid_connect'
      scope:
        - 'openid'
        - 'profile'
        - 'email'
      response_type: 'code'
      issuer: 'https://keycloak.example.com/realms/example'
      discovery: true
      client_auth_method: 'query'
      uid_field: 'preferred_username'
      send_scope_to_token_endpoint: false
      pkce: true
      client_options:
        identifier: '<client_id>'
        secret: '<client_secret>'
        redirect_uri: 'https://code.example.com/users/auth/openid_connect/callback'

Pay attention to the uid_field parameter: the field it points to becomes the account uid, and this value is used when looking the user up in LDAP. It must match the value of the attribute specified in the LDAP server uid parameter (cn in this example), or the email address — for details, see How the LDAP account is found.

The remaining provider parameters are described in the OpenID Connect (OIDC) section.

Verify linking on the first sign-in

To verify linking, follow these steps:

  1. Sign in with a test user through the OIDC provider.
  2. Open the user page in the admin area (/admin/users/<username>/identities). A linked account must have two identities: openid_connect and ldapmain (the LDAP identity name consists of the ldap prefix and the LDAP server name, main in this example).

If the LDAP identity is missing, check the following:

  • the uid or email values match in the OIDC provider and in LDAP;
  • the user falls within the base search scope and is not filtered out by user_filter;
  • the auto_link_ldap_user parameter is enabled.

Rights synchronization

Right after the first sign-in, the user has an account but no group or project memberships. Wait for the next synchronization or run it manually (see Manual synchronization run), then check that:

  • the groups are created inside the group specified in group_sync.top_level_group;
  • the user is added to them with the role matching role_mapping.
←
Authentication / Helm Chart
Administration / Security settings
→