> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/configure/auth/ldap/configure-ldap-authentication/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure LDAP authentication

> Step-by-step procedure to configure LDAP-based authentication and authorization in Itential Platform, including adapter installation, certificate setup, and user group management.

The LDAP adapter establishes a connection with Active Directory and OpenLDAP servers running LDAP version 3. Use this procedure to configure LDAP-based authentication in Itential Platform.

## Before you begin

When using LDAP-based RBAC, understanding group membership is essential for the authorization process. LDAP supports reverse membership mapping when user and group objects use certain object classes. By default, an OpenLDAP system uses the `memberOf` overlay; however, this default can be overridden by the `userMembershipAttribute` property.

## Enable the memberOf module

If using LDAP in a VM or bare-metal (not a container) environment, you must include the `memberof` module in your LDAP config file, otherwise admin permissions will not be granted in Itential Platform.

Every group created before enabling this module must be deleted and re-created for the change to take effect in prior releases.

Delete existing groups:

```bash
sudo ldapdelete -c -D dc=example,dc=com -w <password> -H ldap:/// -f <ldif_file>
```

Include only the DN for each group to remove inside the LDIF file:

```
dn: cn=pronghorn_admin,ou=groups,dc=example,dc=com
```

Then re-add the groups:

```bash
sudo ldapadd -c -D dc=example,dc=com -w <password> -H ldap:/// -f <ldif_file>
```

## Define LDAP groups

Define the groups that will be associated with Itential Platform applications on your authentication server:

* `SystemAdmin`
* `DSOperator`
* `DSManager`
* `DSEngineer`
* `Developer`

![](/_fern-files/itential.docs.buildwithfern.com/2dbc64d0131332467757aa9eabc98da0de11ae06d2fcb6f535bb11616d7a25e9/docs/assets/images/platform/03-defined-groups.png)

## Create an LDAP user for Itential Platform

Create an LDAP user in your authentication database for Itential Platform to use when connecting to the LDAP server to run queries. This user does not need to be a member of any of the defined groups — the user only needs to be able to access the LDAP server.

## Verify the LDAP server connection

Before proceeding, verify the LDAP user can connect to the LDAP server. This step also provides values needed later in the configuration.

Install the `ldapsearch` tool on the Itential Platform server, then run the following commands.

**Ignore certificate key** (run only once per SSH session, and only when connecting via SSL):

```bash
export LDAPTLS_REQCERT=never
```

**Connect using LDAP search:**

```bash
ldapsearch -H ldaps://<IP Address of LDAP Server>:<Port> -b '<Base DN>' -D <UserName>@<Domain> -w '<Password>' cn='<Common Name>' -s sub -x
```

| Parameter                 | Description                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| IP Address of LDAP Server | IP address of your LDAP server, provided by an AD administrator.                                    |
| Port                      | Port of the LDAP server. `636` is standard for SSL connections. `389` is the standard non-SSL port. |
| Base DN                   | Provided by an AD administrator.                                                                    |
| UserName                  | Username created for Itential Platform to connect to AD.                                            |
| Domain                    | Provided by an AD administrator.                                                                    |
| Password                  | Password for the Itential Platform user.                                                            |
| Common Name               | Provided by an AD administrator.                                                                    |

![](/_fern-img/49b9af94e515c6d39ccdfb53b2080e06d8f722fc14ec62d363fe18a4610b63a5.webp)

## Install the LDAP adapter

The LDAP and Local-AAA adapters can both be installed at the same time, but only one adapter may be active at any given time.

![](/_fern-img/b4af64593ef569790cf3c19c1163a4da73655d34bc6a3eff5ac4ac10c86b4786.webp)

Use multiple service config documents for switching between adapters (recommended). The example below shows three adapter configurations: one for the AAA authentication connection, one for the production LDAP server, and one for the staging LDAP server. To change the connection method, exchange the AAA adapter in the active Itential Platform profile and restart the platform. This is only necessary if you expect to switch between authentication methods.

![](/_fern-img/f37c73d0102f4ed98e8af451347bb60b1f924e6002aec0e87803aa5c08b35f7b.webp)

## Install the root certificate

If your LDAP server uses TLS/SSL, the authentication server administrator must provide a certificate for Itential Platform to use.

#### Copy the certificate

Copy the certificate to `/opt/pronghorn/current/custom/keys`.

* This ensures the keys are preserved during a platform upgrade.
* You may need to create the `keys` directory.

#### Verify permissions

Verify the permissions are set to `644`.

## Configure the LDAP adapter

#### Encrypt the bindPassword

Encrypt the `bindPassword` for the LDAP server using the Itential Platform encryption tool:

```bash
cd /opt/pronghorn/current
npm run encrypt <your_password>
```

#### Open Admin Essentials

Navigate to the Admin Essentials homepage.

#### Select the LDAP adapter

In the side navigation menu, expand the **Adapters** collection and select your LDAP adapter. The details view of the adapter opens.

#### Define adapter properties

From the **Configuration** tab, define the adapter properties according to your environment. You can also reference the `DOCUMENTATION.md` file included with the adapter:

```bash
/opt/itential/current/node_modules/@itential/adapter-ldap/docs/DOCUMENTATION.md
```

See [Adapter configuration templates](#adapter-configuration-templates) for sample configurations.

#### Save

Click the **Save** icon to retain your changes.

### Adapter configuration templates

#### Active Directory

```json
{
  "id": "ldap",
  "type": "LDAP",
  "properties": {
    "domain": "example.pronghorn.io",
    "url": "ldaps://example.pronghorn.io:636",
    "bindUsername": "itential",
    "bindPassword": "<your_activeDirectory_password>",
    "baseDN": "dc=itential,dc=io",
    "baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
    "baseUserDN": "ou=people,dc=pronghorn,dc=io",
    "groupSearchFilter": "(objectCategory=Group)",
    "userSearchFilter": "sAMAccountName",
    "userMembershipAttribute": "memberOf",
    "healthCheckInterval": 5000,
    "timeout": 5000,
    "connectTimeout": 5000,
    "idleTimeout": 5000,
    "timeLimit": 10,
    "reconnect": true,
    "activeDirectory": true,
    "tlsOptions": {
      "secureProtocol": "TLSv1_method",
      "requestCert": true,
      "rejectUnauthorized": true,
      "ca": "/etc/ssl/keys/activedirectory_ca.pem"
    },
    "customGroups": [
      "Group1",
      "Group2"
    ]
  },
  "brokers": ["aaa"]
}
```

#### OpenLDAP

The `hostname` in the URL must match the common name of the LDAP server certificate.

```json
{
  "id": "ldap",
  "type": "LDAP",
  "properties": {
    "domain": "uid={0},ou=people,o=support,dc=itential,dc=io",
    "url": "ldaps://example.pronghorn.io:636",
    "bindUsername": "cn=itential,ou=services,o=support,dc=itential,dc=io",
    "bindPassword": "itential-user-password",
    "baseDN": "dc=itential,dc=io",
    "baseGroupDN": "ou=groups,o=support,dc=itential,dc=io",
    "baseUserDN": "ou=people,o=support,dc=itential,dc=io",
    "groupSearchFilter": "(objectClass=groupOfNames)",
    "userSearchFilter": "uid",
    "userMembershipAttribute": "memberOf",
    "healthCheckInterval": 5000,
    "timeout": 5000,
    "connectTimeout": 5000,
    "idleTimeout": 5000,
    "timeLimit": 10,
    "reconnect": true,
    "activeDirectory": false,
    "tlsOptions": {
      "secureProtocol": "TLSv1_method",
      "requestCert": true,
      "rejectUnauthorized": true,
      "ca": "/etc/ssl/keys/openldap_ca.pem"
    }
  },
  "brokers": ["aaa"]
}
```

## Configure the Itential Platform profile

#### Open Admin Essentials

Navigate to the Admin Essentials homepage.

#### Select the active profile

In the side navigation menu, expand the **Profiles** collection and select the active profile. The details view opens.

#### Open authentication properties

On the **Configure** tab, select **authenticationProps** from the **Edit Profile Properties** menu. The authentication properties of the profile display.

#### Define admin groups

Define the default admin groups. Add a list of LDAP groups whose members will be treated as Itential Platform administrators. Use the new adapter ID as **Provenance** and the LDAP group name as the **Group**.

![](/_fern-img/f2ea244e46a6e8b7fd0ad1737262c0f295ecf9b3b54e59594927e2de1019ee23.webp)

#### Save

Click **Save** to retain your changes.

## Verify the LDAP adapter is registered as the AAA broker

Verify the LDAP adapter is registered as the AAA broker in your service config.

**LDAP:**

```json
"brokerProps": {
  "aaa": [
    "LDAP Server"
  ]
}
```

**OpenLDAP:**

```json
"groups": [],
"brokers": ["aaa"]
```

## Verify the LDAP adapter is registered in provenance

```json
"authenticationProps": {
  "admins": [
    {
      "provenance": "LDAP Server",
      "group": "pronghorn_admin"
    }
  ],
  "description": "Authentication",
  "uniqueSession": false
}
```

## Restart Itential Platform

Restart Itential Platform and verify a user can log in as the `admin@pronghorn` user:

```bash
service pronghorn restart
```

## Verify the connection in Itential Platform

#### Log in to Itential Platform

Log in to Itential Platform.

#### Open the Profiles view

Navigate to **Admin Essentials > Profiles**.

#### Check the Adapters tab

Click the **Adapters** tab and locate the LDAP server in the table grid. A status indicator (closed circle) and connection icon (right triangle) indicate whether the server is properly connected. This tab updates every 60 seconds when open.

![](/_fern-img/a6649e39f96c3d6adace0d4ce8ac2c75e69b3c44e84564eff1196c7a86b8db61.webp)

### Troubleshoot connection issues

If you are unable to connect:

1. Run `journalctl -fu itential-platform` to display all output to STDOUT.
2. Try to log in to Itential Platform using the browser — all errors will be displayed.

## Manage access through user groups

After setting up the LDAP adapter, associate your user groups with each Itential Platform application and determine the roles each group will have. This is done through the Groups dialog in Authorization.

Navigate to **Admin Essentials > Authorization > Groups**. A list of all defined roles and groups displays. From this screen, you can assign groups to roles.

![](/_fern-img/c669e0bc38abe788e5ca69e75e93da3829ddf0f532fb55e5c852fbe7fe8c3bc5.webp)

---

## Configure OpenLDAP

Use the following to set up OpenLDAP with `adapter-ldap` for Itential Platform.

The following steps were executed from a CentOS 7 install.

### Install OpenLDAP

#### Install openldap

```bash
yum install -y openldap openldap-clients openldap-servers
```

#### Encrypt the admin password

```bash
[root@localhost cn=config]# slappasswd
New password:
Re-enter new password:
{SSHA}HPHUXuZhbtOs0CIRhnWjglbitrlWt0Lh
```

#### Edit the hdb.ldif file

```bash
vi /etc/openldap/slapd.d/cn=config/olcDatabase\=\{2\}hdb.ldif
```

#### Modify the attributes

Replace the value for `olcRootPW` with the encrypted value from the `slappasswd` command.

```
olcSuffix: dc=pronghorn,dc=io
olcRootDN: cn=admin,dc=pronghorn,dc=io
olcRootPW: {SSHA}HPHUXuZhbtOs0CIRhnWjglbitrlWt0Lh
```

#### Edit the monitor.ldif file

```bash
vi /etc/openldap/slapd.d/cn=config/olcDatabase={1}monitor.ldif
```

#### Modify the access entry

Delete the existing line and replace it with the following:

```
olcAccess: {0}to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external, cn=auth" read by dn.base="cn=admin,dc=pronghorn,dc=io" read by * none
```

#### Validate the configuration

Checksum errors on the two files modified in the previous steps are expected.

```bash
[root@localhost vagrant]# slaptest -u
5a9d88af ldif_read_file: checksum error on "/etc/openldap/slapd.d/cn=config/olcDatabase={1}monitor.ldif"
5a9d88af ldif_read_file: checksum error on "/etc/openldap/slapd.d/cn=config/olcDatabase={2}hdb.ldif"
config file testing succeeded
```

#### Copy the DB\_CONFIG file

```bash
ls -l /var/lib/ldap/DB_CONFIG
cp /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/DB_CONFIG
chown -R ldap:ldap /var/lib/ldap/
```

#### Restart openldap

```bash
systemctl enable slapd
service slapd restart
```

#### Add standard OpenLDAP schemas

```bash
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif
```

#### Add the memberof OpenLDAP schema

For any steps that create an LDIF file, you may need to break the commands down into smaller chunks as illustrated below.

```bash
cat << EOF > /etc/openldap/schema/memberof.ldif
dn: cn=module,cn=config
cn: module
objectclass: olcModuleList
objectclass: top
olcmoduleload: memberof.la
olcmodulepath: /usr/lib64/openldap
EOF

cat << EOF > /etc/openldap/schema/enable-memberof.ldif
dn: olcOverlay={0}memberof,olcDatabase={2}hdb,cn=config
objectClass: olcConfig
objectClass: olcMemberOf
objectClass: olcOverlayConfig
objectClass: top
olcOverlay: memberof
EOF

cat << EOF > /etc/openldap/schema/refint.ldif
dn: cn=module,cn=config
cn: module
objectclass: olcModuleList
objectclass: top
olcmoduleload: refint.la
olcmodulepath: /usr/lib64/openldap
EOF

cat << EOF > /etc/openldap/schema/enable-refint.ldif
dn: olcOverlay={1}refint,olcDatabase={2}hdb,cn=config
objectClass: olcConfig
objectClass: olcOverlayConfig
objectClass: olcRefintConfig
objectClass: top
olcOverlay: {1}refint
olcRefintAttribute: memberof member manager owner
EOF
```

#### Import the schema files

Import in the following order:

```bash
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/memberof.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/enable-memberof.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/refint.ldif
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/enable-refint.ldif
```

#### Add the OpenLDAP schema for users and groups

Replace the `userPassword` component with a value from the `slappasswd` utility. When the `ldapadd` command runs, you will be prompted for a password — enter the OpenLDAP admin password created earlier.

```bash
cat << EOF > /etc/openldap/schema/pronghorn.ldif
dn: dc=pronghorn,dc=io
objectclass: domain
dc: pronghorn

dn: ou=users,dc=pronghorn,dc=io
description: pronghorn users
objectclass: organizationalUnit
ou: users

dn: ou=groups,dc=pronghorn,dc=io
description: pronghorn groups
objectclass: organizationalUnit
ou: groups

dn: uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io
uid: admin@pronghorn
objectClass: inetOrgPerson
cn: admin
sn: admin
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+
EOF
```

#### Import the schema

```bash
ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/pronghorn.ldif
Enter LDAP Password:
adding new entry "dc=pronghorn,dc=io"
adding new entry "ou=users,dc=pronghorn,dc=io"
adding new entry "ou=groups,dc=pronghorn,dc=io"
adding new entry "uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io"
```

#### Verify the connection

Use Apache Directory Studio to connect to the LDAP server and verify the connection and credentials are running as expected.

### Create groups and users in OpenLDAP

Each group object should be created as a `groupOfUniqueNames` with its common name (`cn`) containing the name of the group.

If the group object is a different class (for example, `groupOfNames`), the `groupSearchFilter` in the LDAP adapter properties must match that class (for example, `objectClass=groupOfNames`).

#### Create the following groups in OpenLDAP

| Group           | Description                      |
| --------------- | -------------------------------- |
| `global_admin`  | Multi-tenant administrator group |
| `global_ops`    | Multi-tenant operations group    |
| `tenant1_admin` | Tenant1 administrator group      |
| `tenant1_ops`   | Tenant1 operations group         |
| `tenant2_admin` | Tenant2 administrator group      |
| `tenant2_ops`   | Tenant2 operations group         |

#### Create the following users in OpenLDAP

| User            | First name | Last name | Email                | Groups          |
| --------------- | ---------- | --------- | -------------------- | --------------- |
| `global@admin`  | admin      | global    | `nobody@itential.io` | `global_admin`  |
| `global@ops`    | ops        | global    | `nobody@itential.io` | `global_ops`    |
| `tenant1@admin` | admin      | tenant1   | `nobody@itential.io` | `tenant1_admin` |
| `tenant1@ops`   | ops        | tenant1   | `nobody@itential.io` | `tenant1_ops`   |
| `tenant2@admin` | admin      | tenant2   | `nobody@itential.io` | `tenant2_admin` |
| `tenant2@ops`   | ops        | tenant2   | `nobody@itential.io` | `tenant2_ops`   |

#### Adjust users, passwords, and groups as needed

Adjust the users, passwords, and groups in the sample files if needed.

#### Create the tenant-users.ldif file

```bash
cat << EOF > /etc/openldap/schema/tenant-users.ldif
dn: uid=admin@global,ou=users,dc=pronghorn,dc=io
uid: admin@global
objectClass: inetOrgPerson
cn: admin
sn: global
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+

dn: uid=admin@tenant1,ou=users,dc=pronghorn,dc=io
uid: admin@tenant1
objectClass: inetOrgPerson
cn: admin
sn: tenant1
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+

dn: uid=admin@tenant2,ou=users,dc=pronghorn,dc=io
uid: admin@tenant2
objectClass: inetOrgPerson
cn: admin
sn: tenant2
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+

dn: uid=ops@global,ou=users,dc=pronghorn,dc=io
uid: ops@global
objectClass: inetOrgPerson
cn: ops
sn: global
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+

dn: uid=ops@tenant1,ou=users,dc=pronghorn,dc=io
uid: ops@tenant1
objectClass: inetOrgPerson
cn: ops
sn: tenant1
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+

dn: uid=ops@tenant2,ou=users,dc=pronghorn,dc=io
uid: ops@tenant2
objectClass: inetOrgPerson
cn: ops
sn: tenant2
mail: nobody@pronghorn.io
userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+
EOF
```

#### Import the tenant-users.ldif file

```bash
ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/tenant-users.ldif
```

#### Create the tenant-groups.ldif file

```bash
cat << EOF > /etc/openldap/schema/tenant-groups.ldif
dn: cn=pronghorn_admin,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: pronghorn_admin
member: uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io

dn: cn=global_admin,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: global_admin
member: uid=admin@global,ou=users,dc=pronghorn,dc=io

dn: cn=global_ops,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: global_ops
member: uid=ops@global,ou=users,dc=pronghorn,dc=io

dn: cn=tenant1_admin,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: tenant1_admin
member: uid=admin@tenant1,ou=users,dc=pronghorn,dc=io

dn: cn=tenant1_ops,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: tenant1_ops
member: uid=ops@tenant1,ou=users,dc=pronghorn,dc=io

dn: cn=tenant2_admin,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: tenant2_admin
member: uid=admin@tenant2,ou=users,dc=pronghorn,dc=io

dn: cn=tenant2_ops,ou=groups,dc=pronghorn,dc=io
objectClass: groupOfNames
cn: tenant2_ops
member: uid=ops@tenant2,ou=users,dc=pronghorn,dc=io
EOF
```

#### Import the tenant-groups.ldif file

```bash
ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/tenant-groups.ldif
```

### OpenLDAP configuration example

The `hostname` in the URL must match the common name of the LDAP server certificate.

```json
{
  "id": "ldap",
  "type": "LDAP",
  "properties": {
    "domain": "uid={0},ou=users,dc=pronghorn,dc=io",
    "url": "ldaps://example.pronghorn.io:636",
    "bindUsername": "cn=admin,dc=pronghorn,dc=io",
    "bindPassword": "<your_user_password>",
    "baseDN": "dc=pronghorn,dc=io",
    "baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
    "baseUserDN": "ou=users,dc=pronghorn,dc=io",
    "groupSearchFilter": "(objectClass=groupOfNames)",
    "userSearchFilter": "uid",
    "userMembershipAttribute": "memberOf",
    "healthCheckInterval": 5000,
    "timeout": 5000,
    "connectTimeout": 5000,
    "idleTimeout": 5000,
    "timeLimit": 10,
    "reconnect": true,
    "activeDirectory": false,
    "tlsOptions": {
      "secureProtocol": "TLSv1_method",
      "requestCert": true,
      "rejectUnauthorized": true,
      "ca": "/etc/ssl/keys/openldap_ca.pem"
    }
  },
  "brokers": ["aaa"]
}
```

> Step-by-step procedure to configure LDAP-based authentication and authorization in Itential Platform, including adapter installation, certificate setup, and user group management.