Connect Your LDAP Directory for User Login and Group Sync

Enable LDAP authentication to authenticate users against your existing directory, sync group memberships, or both. You can also use LDAP solely for group sync while keeping an existing SSO provider for login.

Configure LDAP authentication

Configuration

LDAP is configured under the security context of your Kestra Security and Secrets configuration file.

LDAP with Micronaut supports context, search, and groups as core configuration properties. These define the connection context, user attribute mapping, and group filtering needed to synchronize users and their group memberships with Kestra.

The user-attributes section maps LDAP attributes such as givenName, sn, and mail to Kestra user properties (first name, last name, and email).

The mode property controls how Kestra uses the LDAP connection:

The examples below extend the base Micronaut LDAP configuration with these Kestra-specific mappings.

Unix configuration

micronaut:
  security:
    ldap:
      default:
        mode: AUTHENTICATION_AND_GROUP_SYNC  # or AUTHENTICATION to skip group sync
        user-attributes:
          firstName: givenName
          lastName: sn
          email: mail
        context:
          server: "ldap://localhost:389"
          manager-dn: "cn=admin,dc=example,dc=org"
          manager-password: "LDAP_ADMIN_PASSWORD"
        search:
          base: "ou=users,dc=example,dc=org"
          filter: "(mail={0})"
          attributes:
            - "uid"
            - "givenName"
            - "sn"
            - "mail"
        groups:
          enabled: true
          base: "ou=groups,dc=example,dc=org"
          filter: "{&(objectClass=posixGroup)(memberUid={0})}"
          filter-attribute: uid
          attribute: cn

Windows configuration

micronaut:
  security:
    ldap:
      default:
        enabled: true
        mode: AUTHENTICATION_AND_GROUP_SYNC  # or AUTHENTICATION to skip group sync
        user-attributes:
          firstName: givenName
          lastName: sn
          email: userPrincipalName
        context:
          server: "ldaps://<hostname>:636" # ldap://<hostname>:389 for non-TLS
          manager-dn: "CN=********,CN=Users,DC=domain,DC=local"
          manager-password: "********"
        search:
          base: "DC=domain,DC=local"
          filter: "(userPrincipalName={0})"
          attributes:
            - "sAMAccountName"
            - "givenName"
            - "sn"
            - "userPrincipalName"
        groups:
          enabled: true
          base: "DC=domain,DC=local"
          filter: "(&(objectClass=group)(member={0}))"
          filter-attribute: dn
          attribute: cn

Key points for Windows Active Directory:

• Login format: the userPrincipalName filter requires users to log in with their full UPN, e.g. john@domain.local. If your users expect to log in with just their short username (e.g. john), change the filter to (sAMAccountName={0}) and update the email attribute mapping accordingly.
• Search base: setting search.base and groups.base to the root domain (DC=domain,DC=local) covers users and groups across all OUs. Narrow these to a specific OU (e.g. OU=Engineering,DC=domain,DC=local) to restrict access to a subset of your directory.
• Group filter attribute: AD member attributes store full DNs, so filter-attribute: dn is required. Without it, Micronaut defaults to cn and group membership lookups will silently return no results.
• TLS: use ldaps:// on port 636 in production. Plain ldap:// on port 389 sends credentials in cleartext. If your AD uses a self-signed certificate, you must add it to the JVM truststore or configure certificate trust in your Kestra deployment.

Finding Windows Active Directory values

Use the following PowerShell commands on your Windows domain controller to look up the values needed for the configuration above.

LDAP server hostname (context.server)

(Get-ADDomainController).HostName

Use the returned hostname as ldaps://<hostname>:636 for TLS or ldap://<hostname>:389 for non-TLS.

Manager DN (context.manager-dn)

([adsisearcher]"(sAMAccountName=Administrator)").FindOne().Properties.distinguishedname

Replace Administrator with the service account you intend to use as the bind user. The returned distinguished name (DN) is the value for manager-dn.

User distinguished name

To look up the DN of a specific user (useful for verifying your search.base):

Get-ADUser -Identity "JohnDoe" | Select-Object Name, DistinguishedName

Groups for a user

To list the groups a user belongs to (useful for planning your groups.base and groups.filter):

Get-ADPrincipalGroupMembership -Identity "JohnDoe" | Select-Object Name, DistinguishedName

Members of a group

To verify the members of a specific group:

Get-ADGroupMember -Identity "CN=Auto,OU=Distro,OU=Groups,DC=kestra,DC=local" | Select-Object sAMAccountName, Name

Replace the identity string with the DN of your target group.

Group sync with SSO (GROUP_SYNC_ONLY)

If your users already authenticate via SSO, Basic auth, or Passwordless, you can use LDAP solely to resolve group memberships without changing how users log in. Set mode: GROUP_SYNC_ONLY and configure the groups block. No user-attributes mapping is required.

micronaut:
  security:
    ldap:
      default:
        mode: GROUP_SYNC_ONLY
        context:
          server: "ldap://localhost:389"
          manager-dn: "cn=admin,dc=kestra,dc=io"
          manager-password: "LDAP_ADMIN_PASSWORD"
        search:
          base: "ou=users,dc=kestra,dc=io"
          filter: "(mail={0})"
        groups:
          enabled: true
          base: "ou=groups,dc=kestra,dc=io"
          filter: "(member={0})"
          attribute: cn

With this configuration:

• Users log in using their SSO provider. LDAP credentials are never checked.
• At each login, Kestra queries the LDAP directory for the user’s group memberships and merges them with any groups sourced from OIDC claims.
• Groups found in LDAP are synced to Kestra with the same rules as LDAP login: the user joins the existing groups with the same names, as described in LDAP users in Kestra.

Two groups properties control how Kestra reads group entries from the directory:

• filter: the LDAP search filter used to find groups for a user. {0} is replaced with the user’s distinguished name (DN).
• attribute: the attribute on the group entry whose value becomes the Kestra group name. Defaults to cn.
• filter-attribute: the user entry attribute substituted into {0} in the group filter. Use dn for directories that store full DNs in group membership attributes (common in Active Directory). Use uid for POSIX-style directories.

LDAP users in Kestra

On first login with LDAP, Kestra validates the user’s credentials against the directory. When no Kestra user has this email yet, Kestra creates one only if one of the following gives them access:

• One of the user’s LDAP groups exists in Kestra, in any tenant.
• A tenant has a default role.
• The user has a pending invitation. Kestra accepts it at login.

Otherwise, the login is refused and no user is created. If an account already exists, the user authenticates with their LDAP credentials.

Group sync never creates groups. Create the groups in Kestra first, with the same names as the LDAP groups, and bind them to roles in each tenant (see RBAC). At every login, the user joins the existing Kestra groups that match their LDAP groups and leaves the ones LDAP no longer returns, following the group sync rules. Leaving the last group that gave them access to a tenant can remove their access to that tenant.

Group assignments sync only at login. If a user is added to a group in LDAP after their first login, they must log out and back in to pick up the new membership. Any user authenticated via LDAP shows LDAP in the Login & API Tokens column on the IAM → Users page.