Skip to main content
Version: v41

Importing Users from AD/LDAP

This article explains how to configure PrivX to import users from Active Directory (AD) or LDAP directories.

For instructions on integrating other directory types or third-party identity providers, see the articles under User Directories.

Adding AD/LDAP Directories​

Users imported from AD or LDAP can log into PrivX and access target hosts, provided their assigned roles permit it.

To add an AD/LDAP directory to PrivX:

  1. Navigate to Administration→Directories, and click Add Directory.

  2. Set the directory type to either Active Directory or LDAP. Fill in the required directory details, including connection parameters and bind credentials.

    info

    By default, PrivX authenticates users using the userPrincipalName attribute (typically in username@domain format) as username.

    If you prefer users to log in using another attribute, such as uid, you can change the User DN pattern accordingly. For example:

    (uid=%s)

  3. Click Save to apply your changes.

  4. In the Administration→Directories page, you can verify the integration. The directory Status should show OK, and the number of mapped users should match the directory data.

After setup, most users can log into the PrivX web interface using their AD/LDAP credentials. The only exception is users belonging to the AD Protected Users group.

To allow imported users to log into target hosts, assign them to appropriate roles as described in Granting User Permissions.

Secure Connection Setup​

To establish TLS-secured connections (using STARTTLS or LDAPS) to directory servers, ensure the following prerequisites are met:

  • The directory server's certificate must include a Subject Alternative Name (SAN) containing its DNS name and/or IP address.
  • You must obtain the complete CA certificate chain (trust anchors) used by the directory server.

To enable secure connections to user directories:

  1. Verify that the directory server's certificate includes the necessary SAN entries. You can do this by testing the connection (replace directory.example.com and 636 with the actual address and port of your directory server):

    echo "Q" | \
    openssl s_client -connect directory.example.com:636 | \
    openssl x509 -noout -text

    In the output, confirm that the Subject Alternative Name field lists the correct DNS name(s) and/or IP address(es). For example:

    X509v3 Subject Alternative Name:
        DNS:directory.example.com, IP Address:192.0.2.10

  2. In the PrivX GUI, go to Administration → Directories, and click Edit for the directory you want to set up.

  3. Expand the Advanced directory settings section. Under Server authentication settings, do the following:

    • Add the directory server's CA certificate chain to Trust Anchors.
    • Make sure Skip server certificate validation is not selected.

  4. Click Save to apply your changes.

Once these steps are complete, PrivX will establish secure TLS connections to the directory server.

You can confirm the directory status on the Administration→Directories page; it should show a status of OK.

Adjusting User Matching​

PrivX applies a default pre-filter to determine which user records are imported from a directory. You can override this behavior by specifying a custom User Filter for your directory.

Overriding the Pre-Filter for a Specific Directory​

To set a custom user filter for a specific AD/LDAP directory:

  1. Go to Administration→Directories, and click Edit for your target directory.

  2. In the Active Directory settings section, open the Advanced Directory Settings and provide a custom User filter to control which users are matched and imported.

  3. Click Save to apply your changes. Your custom User filter will override the default pre-filter for that directory.

Changing the Global Default User Filter​

You can also change the default user filter globally in PrivX:

  1. Navigate to Administration→Settings.

  2. From the dropdown menu, select Role Store. Under the LDAP section, locate the following settings:

    • Default User Filter: Defines which directory objects are considered users.
    • LDAP Attributes Filter: Specifies which attributes are fetched from matched records.

    Example default values:

    default_user_filter = "(|(objectClass=user)(objectClass=person)(objectClass=inetOrgPerson))"
    attributes = "objectClass cn dn distinguishedName ..."

  3. For a typical OpenLDAP setup, you could, for example, use the following filter to match users with both inetOrgPerson and posixAccount classes:

    default_user_filter = "(&(objectClass=inetOrgPerson)(objectClass=posixAccount))"

  4. If you're using multiple directories with different schemas, you can combine filters like this:

    default_user_filter = "(|(&(objectClass=user)(objectClass=person))(&(objectClass=inetOrgPerson)(objectClass=posixAccount)))"

To allow PrivX role rules to match users in nested groups, you must activate Enable Nested Groups in Role Store's LDAP settings.

Applying Changes​

After modifying any of the global settings, restart PrivX services for changes to take effect:

systemctl restart privx

Refreshing Directory Data​

PrivX keeps user-directory data up to date using both automatic and manual refresh methods.

By default, PrivX refreshes directory data every 15 minutes. To modify the refresh interval for a directory:

  1. Go to Administration→Directories
  2. Click Edit for the target directory.
  3. Adjust the refresh interval as needed:
    • A shorter interval results in faster detection of user changes.
    • A longer interval can help reduce system load.

You can also force an immediate update of directory data:

  1. Navigate to Administration→Directories.
  2. Click Refresh next to the directory you want to update.