Skip to main content

Federate LDAP Users with Keycloak

PaletteAI VM Launchpad uses Keycloak as its OIDC identity provider. If your organization already maintains user accounts in an LDAP directory, you can federate those accounts into Keycloak instead of creating them individually on the Users page.

Federated LDAP users must present an email address before VM Launchpad can identify them and assign VMO roles. Many LDAP directories do not populate an email attribute for every account. This page explains the requirement and how to satisfy it with a Keycloak attribute mapper.

Email Claim Requirement​

The Kubernetes API server in a VM Launchpad cluster runs with --oidc-username-claim=email. Every token the API server accepts must therefore contain both of the following claims.

ClaimRequired ValuePurpose
emailA valid email address, such as user@domainIdentifies the user to the Kubernetes API server.
email_verifiedtrueConfirms the address is trusted. Unverified addresses are rejected.

This is a hard requirement, not a recommendation. When a federated LDAP user has no email address, the Kubernetes API server cannot determine a username for the account, and the following behavior occurs.

  • The user authenticates successfully against Keycloak but has no effective permissions in VM Launchpad.

  • VMO role assignment fails, because the ClusterRoleBindings and RoleBindings that VM Launchpad creates have no subject to bind to.

  • Requests to the Kubernetes API are rejected as unauthenticated.

Creating the user manually on the Users page does not resolve the problem for a federated account. The address must arrive in the token that Keycloak issues, which means that it must come from the LDAP directory or from a Keycloak mapper.

info

VM Launchpad requires the Email field when you create a user directly on the Users page for this same reason. Refer to Create Users.

Prerequisites​

  • A cluster created using VM Launchpad. Refer to Install VM Launchpad for guidance.

  • An account with the Platform Admin VMO role, or membership in a group mapped to Platform Admin.

  • Access to the Keycloak admin console for your appliance. The console is available at https://<platform-ip>/iam, where <platform-ip> is the platform IP address you assigned during cluster creation. Sign in with the Keycloak administrator credentials you set in the Keycloak Admin section of Install VM Launchpad.

  • An LDAP user federation provider already configured in Keycloak. VM Launchpad does not configure LDAP federation for you. Refer to the Keycloak LDAP user federation documentation for setup guidance.

  • An LDAP attribute on each account that holds an email-formatted value. userPrincipalName is a common choice in Active Directory environments, because it stores values in user@domain form.

Map an Email Attribute from LDAP​

Keycloak creates a default email mapper when you add an LDAP provider. That mapper reads the LDAP mail attribute, which many directories leave empty. Edit the mapper so that it reads an attribute that your LDAP directory populates instead. For background on how mappers move attributes between LDAP and Keycloak, refer to the Keycloak LDAP mappers documentation.

  1. Log in to the Keycloak admin console as an administrator.

  2. From the realm drop-down menu at the top of the left main menu, select the realm that holds your VM Launchpad users. On a default appliance, this is the vmo realm. The admin console opens in a different realm, so switch realms before you continue.

  3. From the left main menu, select User federation, and then select your LDAP provider.

  4. Select the Mappers tab.

  5. Select the email mapper. If your provider has no email mapper, select Add mapper and set Mapper type to user-attribute-ldap-mapper.

  6. Complete the following fields.

    FieldValue
    User model attributeemail. The default mapper already uses this value. Leave it unchanged.
    LDAP attributeChange from mail to the attribute that holds an email-formatted value, such as userPrincipalName.
    Always read value from LDAP(Recommended) Set to On so that Keycloak refreshes the address from the directory on every sync. Defaults to Off.
    Is mandatory in LDAP(Optional) Set to On so that accounts missing the attribute fail the sync instead of importing without an address. Defaults to Off.
  7. Select Save.

warning

Do not create a second mapper that also writes to the email user model attribute. Two mappers that target the same attribute produce unpredictable results. Edit the existing email mapper instead.

Trust Email Addresses from LDAP​

The mapper populates the email claim, but the token still needs email_verified: true. Keycloak marks a federated address as verified only when the LDAP provider is configured to trust it. Trust Email is a setting on the LDAP provider itself, not on the mapper, and it defaults to Off.

tip

Enable Trust Email when you first create the LDAP provider to avoid correcting accounts afterward.

  1. In the Keycloak admin console, select User federation, and then select your LDAP provider.

  2. Scroll to the Advanced settings section, which is the last section on the provider settings page.

  3. Set Trust Email to On.

  4. Select Save.

With Trust Email enabled, Keycloak accepts the address that the directory supplies without sending a verification email, and includes email_verified: true in the tokens that it issues.

Synchronize LDAP Users​

Accounts that Keycloak imported before you made these changes keep their original attributes. Run a new synchronization so that the mapper applies to them.

  1. In the Keycloak admin console, select User federation, and then select your LDAP provider.

  2. From the Action drop-down menu, select Sync all users.

  3. Wait for the synchronization to complete. Keycloak reports the number of accounts added and updated.

A synchronization updates the email attribute on accounts that Keycloak already imported, and it applies Trust Email to accounts that it imports for the first time. It does not apply Trust Email to accounts that already exist, because Keycloak sets the verified flag only during the initial import of an account.

Correct Previously Imported Accounts​

Accounts that Keycloak imported before you enabled Trust Email keep email_verified: false and still cannot sign in, even after the synchronization reports them as updated. Use one of the following approaches to correct them.

  • Set the flag for each account. On the Users page, select the account, set Email verified to On, and save. Use this approach when only a few accounts are affected.

  • Import the accounts again. From the LDAP provider's Action drop-down menu, select Remove imported, and then select Sync all users. Keycloak deletes its local copies and imports them again, which applies Trust Email.

warning

Remove imported deletes the local Keycloak record for every account imported from the provider. Group memberships and role mappings assigned in Keycloak, rather than derived from LDAP, are lost and must be assigned again. Because VM Launchpad maps VMO roles through Keycloak groups, review group membership and role assignments after the re-import. Refer to Groups.

Refresh Existing Sessions​

Users who are already signed in continue to hold their previous token until it expires, and that token does not carry the new email claim. Ask affected users to sign out and sign in again to receive an updated token. API keys created before the change also keep the old claims until the user signs in again.

Verify​

  1. In the Keycloak admin console, select Users from the left main menu, and then select a federated account. Confirm that the Email field is populated and that Email verified is enabled.

  2. Log in to VM Launchpad.

  3. From the left main menu, select Settings > Access Management > Users.

  4. Confirm that the federated account appears in the table and that the Email column shows an address.

  5. Assign a VMO role and namespace scope to the account. Refer to Edit a User, or add the account to a group that already carries a role. Refer to Groups.

  6. Ask the user to sign in and confirm that the resources that their role grants are available.

If the account still has no email address after a synchronization, the LDAP attribute that you mapped is not populated for that account. Refer to Troubleshooting VM Launchpad.

Next Steps​

  • Group federated users together and manage their VMO role and Kubernetes access in one place. Refer to Groups.

  • Review how VM Launchpad combines role grants from users and groups. Refer to How Effective Permissions Are Calculated.