Configure LDAP authentication

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:

$ 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:

$ 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

Defined groups in the authentication server

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):

$ export LDAPTLS_REQCERT=never

Connect using LDAP search:

$ 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.

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.

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.

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:

$ 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:

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

See Adapter configuration templates for sample configurations.

Save

Click the Save icon to retain your changes.

Adapter configuration templates

Active Directory

1 {
2   "id": "ldap",
3   "type": "LDAP",
4   "properties": {
5     "domain": "example.pronghorn.io",
6     "url": "ldaps://example.pronghorn.io:636",
7     "bindUsername": "itential",
8     "bindPassword": "<your_activeDirectory_password>",
9     "baseDN": "dc=itential,dc=io",
10     "baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
11     "baseUserDN": "ou=people,dc=pronghorn,dc=io",
12     "groupSearchFilter": "(objectCategory=Group)",
13     "userSearchFilter": "sAMAccountName",
14     "userMembershipAttribute": "memberOf",
15     "healthCheckInterval": 5000,
16     "timeout": 5000,
17     "connectTimeout": 5000,
18     "idleTimeout": 5000,
19     "timeLimit": 10,
20     "reconnect": true,
21     "activeDirectory": true,
22     "tlsOptions": {
23       "secureProtocol": "TLSv1_method",
24       "requestCert": true,
25       "rejectUnauthorized": true,
26       "ca": "/etc/ssl/keys/activedirectory_ca.pem"
27     },
28     "customGroups": [
29       "Group1",
30       "Group2"
31     ]
32   },
33   "brokers": ["aaa"]
34 }

OpenLDAP

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

1 {
2   "id": "ldap",
3   "type": "LDAP",
4   "properties": {
5     "domain": "uid={0},ou=people,o=support,dc=itential,dc=io",
6     "url": "ldaps://example.pronghorn.io:636",
7     "bindUsername": "cn=itential,ou=services,o=support,dc=itential,dc=io",
8     "bindPassword": "itential-user-password",
9     "baseDN": "dc=itential,dc=io",
10     "baseGroupDN": "ou=groups,o=support,dc=itential,dc=io",
11     "baseUserDN": "ou=people,o=support,dc=itential,dc=io",
12     "groupSearchFilter": "(objectClass=groupOfNames)",
13     "userSearchFilter": "uid",
14     "userMembershipAttribute": "memberOf",
15     "healthCheckInterval": 5000,
16     "timeout": 5000,
17     "connectTimeout": 5000,
18     "idleTimeout": 5000,
19     "timeLimit": 10,
20     "reconnect": true,
21     "activeDirectory": false,
22     "tlsOptions": {
23       "secureProtocol": "TLSv1_method",
24       "requestCert": true,
25       "rejectUnauthorized": true,
26       "ca": "/etc/ssl/keys/openldap_ca.pem"
27     }
28   },
29   "brokers": ["aaa"]
30 }

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.

Defining admin groups in authenticationProps

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:

1 "brokerProps": {
2   "aaa": [
3     "LDAP Server"
4   ]
5 }

OpenLDAP:

1 "groups": [],
2 "brokers": ["aaa"]

Verify the LDAP adapter is registered in provenance

1 "authenticationProps": {
2   "admins": [
3     {
4       "provenance": "LDAP Server",
5       "group": "pronghorn_admin"
6     }
7   ],
8   "description": "Authentication",
9   "uniqueSession": false
10 }

Restart Itential Platform

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

$ service pronghorn restart

Verify the connection in 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.

Troubleshoot connection issues

If you are unable to connect:

Run journalctl -fu pronghorn to display all output to STDOUT.
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.

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

$ yum install -y openldap openldap-clients openldap-servers

Encrypt the admin password

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

Edit the hdb.ldif file

$ 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

$ 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.

$ [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

$ 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

$ systemctl enable slapd
$ service slapd restart

Add standard OpenLDAP schemas

$ 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.

$ 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:

$ 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.

$ 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

$ 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

$ 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

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

Create the tenant-groups.ldif file

$ 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

$ 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.

1 {
2   "id": "ldap",
3   "type": "LDAP",
4   "properties": {
5     "domain": "uid={0},ou=users,dc=pronghorn,dc=io",
6     "url": "ldaps://example.pronghorn.io:636",
7     "bindUsername": "cn=admin,dc=pronghorn,dc=io",
8     "bindPassword": "<your_user_password>",
9     "baseDN": "dc=pronghorn,dc=io",
10     "baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
11     "baseUserDN": "ou=users,dc=pronghorn,dc=io",
12     "groupSearchFilter": "(objectClass=groupOfNames)",
13     "userSearchFilter": "uid",
14     "userMembershipAttribute": "memberOf",
15     "healthCheckInterval": 5000,
16     "timeout": 5000,
17     "connectTimeout": 5000,
18     "idleTimeout": 5000,
19     "timeLimit": 10,
20     "reconnect": true,
21     "activeDirectory": false,
22     "tlsOptions": {
23       "secureProtocol": "TLSv1_method",
24       "requestCert": true,
25       "rejectUnauthorized": true,
26       "ca": "/etc/ssl/keys/openldap_ca.pem"
27     }
28   },
29   "brokers": ["aaa"]
30 }