Configure an LDAP authentication

In this topic, you learn how to create and configure an LDAP authentication in the Cockpit.

Prerequisites

  • You have access to an LDAP directory (Active Directory or OpenLDAP).

  • You have an LDAP server address, bind credentials, and base DN.

  • You have created roles and security groups in the Cockpit (recommended).

Procedure

Create the LDAP authentication entry

Establish a new LDAP authentication object in the Cockpit, which is fully configured in later steps.

  1. Go to System Settings → Authentication → Edit → Add → LDAP.

    Result: The Authentication dialog opens.

  2. Fill in the basic fields:

    1. Name: Enter a descriptive name for the LDAP connection.

      Example: CorporateLDAP.

    2. Active (optional): Select to enable immediately.

    3. Show on Login Page (optional): Select to let users select LDAP at login.

    4. Description: Enter a short text explaining the purpose of the connection.

      Example: Authentication for corporate directory users.

    5. Allow Unauthorized Certificates (optional): Select only if your LDAP server uses self-signed TLS certificates.

Configure the LDAP connection endpoint

These fields define where and how the instance of Neptune DXP - Open Edition connects to the LDAP server. Fill them according to the following instructions:

  • Path

  • URL

    • Purpose: LDAP server address and protocol.

    • Required: Yes

      Example: ldap://ldap.example.org:389 (standard, no TLS)

      Example: ldaps://ad.example.org:636 (LDAP over TLS)

      Use ldaps:// for secure connections. The port must match the server config.
      If TLS and self-signed certificate, enable Allow Unauthorized Certificates or the connection fails.

Configure bind account and search scope

Aim: Provide credentials for a service account and specify the base subtree for searching users/groups.

  • Bind DN: Enter the distinguished name of the service account.

    • Required: Yes

      Example (OpenLDAP): uid=ldapreader,ou=users,dc=example,dc=org

      Example (Active Directory): CN=LDAP Reader,OU=Service Accounts,DC=example,DC=org

      The distinguished name requires read access to user/group entries.

  • Bind Credentials: Password for Bind DN.

    • Required: Yes

  • Search Base: Base DN where searches start.

    • Required: Yes

      Example: ou=users,dc=example,dc=org or DC=example,DC=org

      Users/groups outside this subtree will not be found.

Configure login-time access filters

Aim: Restrict authentication to authorized users/groups.

  • Filter for User Login: Identifies valid user objects.

    • Required: Yes

      Example (Generic): (uid={{username}})

      Example (Active Directory): (&(objectClass=user)(sAMAccountName={}))

      Placeholders between braces like {{username}} are automatically replaced by the server when processing the request.

  • Filter for groups on user login (optional): Restricts login to users who are in matching groups.

    Example (UI placeholder): (&(objectclass=posixGroup)(memberUID={}))

Configure filter search behavior

Aim: Define how the system locates user and group entries during authentication and lookup operations.

The filters in this step determine which directory objects are considered users or groups, and how broadly the directory is searched. These filters ensure only valid user objects are returned, reducing false matches and login errors. Start with restrictive filters to ensure correctness, then expand them only if required.

  • User Filter

    • Purpose: Defines which directory entries are treated as users.

    • Required: Yes

      Example (Active Directory): (objectClass=user)

      Example (OpenLDAP): (objectClass=posixUser)

      Avoid adding name-based or wildcard conditions at this stage; those are better suited for interactive searches, not authentication.

  • Group Filter

    • Purpose: Defines which directory entries are treated as groups.

    • Required: Yes

      Example (Active Directory): (objectClass=group)

      Example (Open LDAP): (objectClass=posixGroup)

      This ensures only actual group objects are evaluated during group resolution and mapping.

      In Neptune DXP - Open Edition, broader filters (for example, matching common names or descriptions) are shown are placeholders. These are useful for search and discovery, but are optional for authentication and can be introduced later if broader matching is required.

Configure user filtering

Aim: Identify user entries and define how users are uniquely identified.

  • User Filter

    • Purpose: Specifies the LDAP search condition used to identify user objects in the directory. Only directory entries matching this filter are treated as users by the system.

    • Required: Yes

      Example: objectClass=groupofnames

      This should match the same user object type used earlier in authentication and search filters.

  • Unique Identifier

    • Purpose: Uniquely identifies each user across the search base.

    • Required: Yes

      Example: cn (readable and unique enough in smaller directories)

      Example (Active Directory): objectGUID

      Example (OpenLDAP): entryUUID

      Changing this value later can cause duplicate users to be created.

Map LDAP user attributes

Aim: Map LDAP attributes to application user fields, entering LDAP attribute names exactly as they exist in your directory schema.

  • User ID

    • Purpose: Identifies the user within the application (login identifier).

    • Required: Yes

      Example (Active Directory): sAMAccountName or userPricipalName

      Example (OpenLDAP): uid

  • User Name

    • Purpose: Display name shown in the UI.

    • Required: No

      Example (both Active Directory and OpenLDAP): cn

      If left empty, the User ID may be shown instead.

  • eMail

    • Purpose: Stores the user’s email address.

    • Required: No

      Example (both Active Directory and OpenLDAP): mail

  • Mobile

    • Purpose: Stores the user’s mobile phone number.

    • Required: No

      Example (both Active Directory and OpenLDAP): mobile

  • Phone

    • Purpose: Stores the user’s phone number.

    • Required: No

      Example (both Active Directory and OpenLDAP): telephoneNumber

  • Groups

    • Purpose: Determines which groups the user belongs to.

    • Required: No

      Example (Active Directory): memberOf

      Example (OpenLDAP): memberOf (requires the memberOf overlay)

Configure group filtering

Aim: Identify group entries and define how groups are uniquely identified.

  • Group Filter

    • Purpose: Specifies the LDAP search condition used to identify group objects in the directory. Only directory entries matching this filter are treated as groups by the system.

    • Required: Yes

      Example (Active Directory): objectClass=group

      Example (OpenLDAP): (objectClass=posixGroup)

      A filter that is too broad may include unintended objects, while a filter that is too narrow may prevent valid groups from being detected.

  • Unique Identifier

    • Purpose: Defines the LDAP attribute used as the unique ID for each group.

    • Required: Yes

      This value must be unique for every group under the configured search base so the system can consistently reference and map groups.

      Example: cn (human-readable and typically unique within a directory)

Map LDAP group attributes

Aim: Define how group information is imported and displayed.

  • Name

    • Purpose: Display name of the group.

    • Required: Yes

      Example: CN / OU

  • Description

    • Purpose: Human-readable description of the group.

    • Required: No

      Example: description / gidComment (custom attribute)

      Leave empty if your directory does not store group descriptions.

Configure automatic role and group assignment

  1. In the Auto Assignment section, select the roles and security groups that should be assigned to users who authenticate via this LDAP connection. These roles and groups must already exist and be defined in the Role and Security Group tools.

  2. Select Only Assign on First Login to apply these assignments only when a user logs in for the first time to ensure that automatically assigned roles and groups are applied once during initial user creation, but are not re-applied on subsequent logins.

    This is useful when:

    • user permissions may be adjusted manually after the first login,

    • role or group membership is managed outside LDAP,

    • you want to prevent later logins from overwriting manual changes.

    If this option is not selected, the selected roles and groups are re-evaluated and applied on every login, which may override manual role or group changes.

Activate the configuration

  1. Apply the LDAP authentication settings by selecting OK to save the configuration.

  2. In the System Settings tool, select Restart to activate the LDAP authentication.

Results

  • You have created and activated an LDAP authentication method that connects to your directory server and validates user credentials.

  • Users and groups are now identified, filtered, and mapped according to your configuration.

  • Users can sign in using their LDAP credentials and are automatically assigned roles and security groups, either on first login or on every login, depending on your settings.

Related topics