Skip to content

LDAP and Active Directory

If your organisation uses LDAP or Active Directory to manage users, you can connect Keycloak to your directory service using User Federation. This replaces the LDAP configuration that was previously done in Altair SLC Hub YAML configuration files.

Where to configure it

  1. Navigate to the Keycloak Admin console in the browser.

  2. In the left menu, click User Federation.

  3. Click Add provider and select Add Ldap providers.

  4. Fill in the necessary connection details.

Keycloak Documentation

For general LDAP federation configuration, see the official Keycloak documentation: Keycloak — LDAP and Active Directory.

Configure attribute mappers

Why attribute mappers are required

Keycloak includes a set of default LDAP mappers, but several of them are pre-configured with values that do not match what Altair SLC Hub requires. In previous versions of Altair SLC Hub, these mappings were applied automatically. They must now be configured manually.

Without correct mappers: Users may sync successfully but have incorrect names, missing home directories, or be unable to run workloads — depending on your worker environment.

For detailed instructions on LDAP mappers in Keycloak, see Mapping claims and assertions in the official Keycloak documentation.

To manage mappers:

  1. In User Federation, select your LDAP provider.
  2. Go to the Mappers tab.

Required attribute mappers

Keycloak's LDAP integration is flexible, but Altair SLC Hub has specific requirements. For Altair SLC Hub to run jobs as the correct OS user, the following attributes must be mapped from your LDAP directory to the corresponding Keycloak user attributes:

Attribute Description
Unix username The OS-level username Altair SLC Hub uses to run jobs
UPN (User Principal Name) Used for user identification and authentication
Unix user home path The home directory Altair SLC Hub uses when running jobs

If these mappings are missing or incorrect, Altair SLC Hub cannot run jobs as the correct user. This is the most common source of problems when setting up LDAP with Altair SLC Hub.

Configure group mappers

If your organization uses LDAP groups and you want to import them into Altair SLC Hub, you must create a group mapper in addition to the user attribute mappers.

Why group mappers are required

By default, when you set up LDAP user federation, you're only importing users. If you also want to import groups from your LDAP directory, you need a separate group mapper to tell Keycloak where to find them.

Create the LDAP group mapper

To import groups from your LDAP directory:

  1. In User Federation, select your LDAP provider.

  2. Go to the Mappers tab and click Add mapper.

  3. Set Mapper type to group-ldap-mapper.

  4. Configure the LDAP group mapper fields with values appropriate for your LDAP directory. For detailed guidance on these fields, see Mapping claims and assertions in the Keycloak documentation.

  5. Configure these fields specifically for Altair SLC Hub:

    Field OpenLDAP Active Directory
    Name ldap-groups ldap-groups
    Mapped Group Attributes entryUUID objectGUID
    Decode UUID Attribute to UUID Format OFF ON

    These fields tell Altair SLC Hub how to recognize groups as external (sourced from LDAP).

  6. Click Save.

OpenLDAP vs Active Directory

The specific attribute names and values differ between OpenLDAP and Active Directory. Use the values that correspond to your directory service. For details on LDAP attribute standards, see the LDAP RFC 4876 and Active Directory Schema.

For detailed instructions on LDAP group mappers, see Mapping claims and assertions in the official Keycloak documentation.

Sync LDAP groups

After creating the group mapper, you can import your LDAP groups into Keycloak:

  1. In User Federation, select your LDAP provider.

  2. Go to the Mappers tab and click the ldap-groups mapper.

  3. Click Action > Sync LDAP groups to Keycloak.

This imports your LDAP groups into Keycloak and marks them as external groups,so groups are correctly identified as external when listing groups or showing the group membership of a user.

Re-sync after mapper changes

If you modify the group mapper configuration, you must click Action > Sync LDAP groups to Keycloak again for the changes to take effect on existing groups.

Configure sync settings

After saving your LDAP settings, click the Action dropdown in the top-right corner of the LDAP settings page. From there you can choose:

Option Description
Sync changed users Only imports users that have been added or modified in your LDAP directory since the last sync.
Sync all users Imports all users from your LDAP directory into Keycloak.

Important

You must trigger Sync all users from the Action dropdown after making any changes to mappers for those changes to take effect on existing users. Newly synced users will automatically pick up the current mapper configuration.

Attribute value templates

In previous Altair SLC Hub releases, you could use a Golang template to transform an LDAP attribute value on import. For example, you could change a cn value to upper case before Altair SLC Hub stored it as the username. Keycloak does not support Golang templates.

Altair SLC Hub supplies a mapper that does the same work with a FreeMarker template. The transformation is one-directional, from LDAP to Keycloak.

To add the mapper:

  1. In User Federation, select your LDAP provider.

  2. Go to the Mappers tab and click Add mapper.

  3. Set Mapper type to templated-user-attribute-ldap-mapper.

  4. Complete the fields:

    Field Description
    LDAP Attribute The name of the LDAP attribute to read, for example cn, sn, or mail
    Value Template The FreeMarker template to apply to the value. The raw LDAP value is available as ${ldapValue}
    User Model Attribute The Keycloak user attribute to write, for example firstName, unixUserName, or unixHomeDirectory

  5. Click Save, then click Action > Sync all users to apply the mapper to the existing users.

These examples show the FreeMarker equivalent of a Golang template:

Transformation Value Template
Upper case, previously upper ${ldapValue?upper_case}
Lower case, previously lower ${ldapValue?lower_case}
Take the part before @ ${ldapValue?keep_before("@")}
Replace a substring ${ldapValue?replace("foo","bar")}
Add a prefix corp-${ldapValue?lower_case}
No transformation ${ldapValue}

Note

Keycloak stores usernames in lower case. A template that makes the username upper case has no effect on the Keycloak username.

Scripted configuration

For administrators who need to configure Keycloak from the command line or via scripts, a Keycloak admin utility is available at:

slchub/libexec/keycloak/kcadm.sh

This can be used to configure user federation, identity providers, and other Keycloak settings without using the Admin Console UI.

hubctl LDAP commands

The hubctl LDAP commands are no longer functional. They will remain in place temporarily and print a warning when invoked. LDAP configuration must now be done in the Keycloak Admin Console.

Troubleshooting

Users' first name shows their full name

Symptom: After syncing, a user's first name field contains their full name (e.g., Jane Smith) instead of just their given name (e.g., Jane).

Cause: Keycloak's default first name mapper reads from the cn (common name) LDAP attribute, which typically contains the full name rather than the given name.

Fix: Update the first name mapper to use givenName instead:

  1. In User Federation, select your LDAP provider.
  2. Go to the Mappers tab.
  3. Find the first name mapper and click it.
  4. Change LDAP attribute from cn to givenName.
  5. Click Save.
  6. Click Action > Sync all users to apply the change to existing users.

Groups appear as local instead of external

Symptom: After syncing LDAP groups into Altair SLC Hub, groups show as local instead of external. This means Altair SLC Hub doesn't recognize them as LDAP-managed groups.

Root cause: The Mapped Group Attributes field in your group mapper was not configured, or it was set to the wrong value. Without this field, groups are imported but marked as local.

Fix: Configure the Mapped Group Attributes field in your group mapper:

  1. Go to User Federation > select your LDAP provider > Mappers tab.
  2. Click Add mapper and follow the steps in Create the LDAP group mapper.
  3. After you save, click Action > Sync LDAP groups to Keycloak to import your groups.

Verify it worked:

  1. Go to Groups in the left menu.
  2. Select one of your imported groups.
  3. Click the Attributes tab.
  4. Look for an attribute called entryUUID (OpenLDAP) or objectGUID (Active Directory).
  5. If you see this attribute with a value, your group is now marked as external, the fix worked.

If the attribute is missing: The Mapped Group Attributes field in your group mapper was set incorrectly. Go back to Create the LDAP group mapper and double-check that you used entryUUID (OpenLDAP) or objectGUID (Active Directory).