LDAP for Users

LDAP authentication enables UDMG to integrate with your existing enterprise identity systems, such as Microsoft Active Directory or OpenLDAP. You can configure LDAP authentication for UDMG Users independently from Accounts, and each can connect to a different directory provider if needed.

Once configured, UDMG Users authenticate using their LDAP credentials, reducing administrative overhead, ensuring consistent access policies, and enhancing overall security.

info

LDAP also uses the concept of a user. To avoid confusion, this page uses two terms: "UDMG User" for the UDMG configuration item, and "LDAP user" for the corresponding user entry in the LDAP directory.

Before You Begin

LDAP Sync

UDMG Users are automatically synchronized with the LDAP server every day at midnight by default.

You can also trigger a Sync manually via the Sync LDAP button (next to the Test LDAP button).

During an LDAP Sync, UDMG compares the LDAP users returned from the LDAP server with the UDMG Users in the UDMG database.

If an LDAP user does not have a corresponding UDMG User, a new User record is automatically created in UDMG.

This diagram describes the process of synchronizing LDAP users with UDMG Users. It covers checking for existing UDMG Users, creating new Users, and updating User information.

%%{init: {'theme': 'default', 'themeVariables': { 'fontSize': '18px' }}}%%
flowchart
    classDef highlighted fill:#d4e8ff,stroke:#1890ff,stroke-width:3px,color:#000
    classDef userProcess fill:#e6f7ff,stroke:#69c0ff,stroke-width:2px
    classDef accountProcess fill:#f6ffed,stroke:#95de64,stroke-width:2px
    classDef errorProcess fill:#fff2e8,stroke:#ffa39e,stroke-width:2px

    ProcessUser["Process User"] --> CheckUserExistsInDB{{"User exists in database?"}}
    CheckUserExistsInDB -->|No| CreateNewUser["Create new user:
    - **Username** from LDAP
    - Display **Name** from LDAP
    - **Email** from LDAP
    - **Login Method** = LDAP
    - **Enabled** = true
    - **Source** = LDAP server URL
    - **Role** = Read-only"]

    CreateNewUser --> LogProcessed

    CheckUserExistsInDB -->|Yes| CheckIsLDAPUser{{"Is **Login Method** LDAP?"}}

    CheckIsLDAPUser -->|No| SkipUserProcessing["Skip non-LDAP User processing"]

    CheckIsLDAPUser -->|Yes| CheckIfFieldsNeedUpdate["Check fields for updates:
    - Is **Email** different?
    - Is display **Name** different?"]

    CheckIfFieldsNeedUpdate --> AnyUpdatesNeeded{{"Any updates needed?"}}
    
    AnyUpdatesNeeded -->|No| LogNoChanges["Log: No updates needed"]
    AnyUpdatesNeeded -->|Yes| UpdateChangedFields["Update only changed fields:
    - **Email**
    - Display **Name**"]

    SkipUserProcessing --> LogProcessed["Log: User processed"]
    LogNoChanges --> LogProcessed
    UpdateChangedFields --> LogProcessed
    
    LogProcessed --> UserComplete["User processing complete"]

Sync Result

After the Sync completes, a popup displays the sync status and the number of LDAP users synced. Four metrics are given:

Name	Description
Processed	Number of UDMG Users synced.
Skipped	Number of LDAP users whose corresponding UDMG User did not require creation or updates.
Failed	Number of LDAP users that failed to sync (due to some system failure).
Total	Total number of LDAP users returned by the LDAP server.

info

These metrics only count UDMG Users with Login Method = LDAP.

LDAP Sync Interval

You can configure the Sync interval for UDMG Users in the ldap block in the Configuration File.

udmg-server.hcl

ldap {
    ldap_user_sync_interval    = "1h"
}

info

For more information on the ldap.ldap_user_sync_interval field, see Configuration File.

LDAP Configuration

LDAP is configured at the Domain level, meaning it can only be used to authenticate UDMG Users within the specific Domain. If you want to use the same LDAP provider across multiple Domains, it must be configured separately in each Domain.

To configure LDAP settings for UDMG Users in your Domain, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click User LDAP Authentication.
3. Click Edit.
4. Fill out the fields for the new LDAP settings using the Field Descriptions table as a guide.
5. Click Update.

info

Only Admins can configure LDAP authentication.

warning

LDAP-provisioned UDMG Users are given the Read-only Role. If they need additional access, Admins must change the Role by following these steps.

Field Descriptions

Name	Description	Specifications	Required
LDAP Host	The host and optional port of the LDAP server (e.g., ldap.example.com:389).	If the port is not supplied, it will be guessed based on the TLS configuration.	Yes
Description	Optional description for this LDAP configuration.		No
Use SSL/TLS Connection	A toggle switch to enable or disable SSL/TLS. If SSL/TLS is enabled, the root certificate installed on the system will be used.	Default value: Enabled.	Yes
Bind DN	The distinguished name (DN) of the user account used to bind to the LDAP server. The connector uses this DN to search for UDMG Users.		Yes
Bind Credentials	The Credential containing the password for the Bind DN. The connector uses these Credentials to search for UDMG Users.	Must reference an already created Username and Password.	Yes, if Use SSL/TLS Connection is enabled.
Base DN	The Base DN from where to start the LDAP user search. For example, dc=udmg,dc=local.		Yes
User ID Attribute	The LDAP attribute containing the UDMG User's Username to map.		Yes
User Filter	The LDAP filter applied when searching the directory for LDAP user entries (e.g., (objectClass=person)). If the field contains an * ((objectClass=*)), then both LDAP user and LDAP group entries are pulled into UDMG.		Yes
UDMG to LDAP Attribute Mapping	Map LDAP attributes to UDMG User fields. Enter the exact attribute name from your LDAP provider for each of the fields: First Name Last Name Email		No

LDAP Test

After configuring an LDAP provider, you can test the connection to UDMG.

Click the Test LDAP button above the LDAP configuration details.

A popup indicates whether the system was able to connect successfully. If the connection was successful, the popup displays the number of LDAP users retrieved that match the User Filter.

info

Testing the LDAP connection does not synchronize the LDAP server with UDMG. The test simply reports the status of the connection.

Managing an LDAP Configuration

Viewing LDAP Configuration Details

To view the details of an LDAP configuration, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click the User LDAP Authentication card.

LDAP Configuration Metadata

LDAP configuration details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

Name	Description
UUID	Universally Unique Identifier of this LDAP configuration.
Version	Version number of the latest configuration of the LDAP configuration.
Created	Date and time this LDAP configuration was created.
Updated	Date and time this LDAP configuration was last updated.

Editing LDAP Configuration Details

To edit the details of an LDAP configuration, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click the User LDAP Authentication card.
3. Edit details for the LDAP settings, using the Field Descriptions table as a guide.
4. Click Update.

Deleting an LDAP Configuration

Deleting an LDAP configuration is straightforward; however, you must plan what to do with any orphaned UDMG Users that have already been provisioned. Those options include:

Option	When to Choose	Result
Delete the Users	No plans to migrate to a new configuration, or don't want to preserve the records.	Users are removed from UDMG; if they authenticate later via an active LDAP configuration, they will be re-provisioned.
Retain as orphaned	You need the records for auditing but do not want Users to log in.	Users remain visible but cannot authenticate; even with a new LDAP configuration, their usernames remain tied to the deprecated LDAP configuration.

To delete an LDAP configuration, follow these steps:

1. From the Sidebar, click General > Settings.
2. Click the User LDAP Authentication card.
3. Click the Delete button above the LDAP configuration details.
4. You will be asked to confirm the deletion. Click Continue.

info

Deleting an LDAP configuration blocks new login attempts for associated Users. Existing sessions remain active until they expire or the User logs out.

Managing LDAP-Provisioned UDMG Users

Editing LDAP-Provisioned UDMG Users

To edit the details of an LDAP-provisioned UDMG User, follow these steps:

1. From the Sidebar, click General > Users.
2. Click the Username of the User you want to edit.
3. Click the Edit button above the User details.
4. Only the Require Two-factor Authentication (TOTP) and Role fields are editable.
5. Click Update.

Deleting LDAP-Provisioned UDMG Users

To delete an LDAP-provisioned UDMG User, follow these steps:

1. From the Sidebar, click General > Users.
2. Click the Username of the User you want to delete.
3. Click the Delete button above the details.
4. You will be asked to confirm the deletion. Click Continue.

warning

Deleting an LDAP-provisioned UDMG User only removes the local record, but it will reappear after the next LDAP sync if it still exists in LDAP and matches the sync criteria. To permanently revoke access, remove the LDAP user from LDAP first, then optionally delete it from the UDMG Users page.