Tips for LDAP and LDAPS

LDAP (protocol)

“The Lightweight Directory Access Protocol is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network.

LDAP is specified in a series of Internet Engineering Task Force (IETF) Standard Track Request for Comments (RFCs). The latest specification is Version 3, published as RFC 4511.

A common use of LDAP is to provide a central place to store usernames and passwords. This allows many different applications and services to connect to the LDAP server to validate users.

LDAP is based on a simpler subset of the standards contained within the X.500 standard.”

Syndeia administrators can use any Identity Provider (IdP) that implements an LDAP or Secure LDAP interface as one of the optional choices for delegated authentication in Syndeia. (There are other non-LDAP choices that could be made.)

Syndeia interfaces with LDAP servers using RFC 4511 standard LDAP URL requests.

Tip: Research the configuration for LDAP outside of Syndeia

The recommended way to discover how to configure Syndeia for LDAP-speaking IdPs is to use one of the several open-source utilities for LDAP searching. These include:

ldapsearch (https://man7.org/linux/man-pages/man1/ldapsearch.1.html )
curl
openssl_client
and Apache Directory Studio

This article only gives examples using ldapsearch - but the tactics are easily performed with the other tools.

For all the examples, the LDAP server being queried is shown as myldap.acme.org. Actual queries must use actual hostnames.

Tip: How to search an open, simple LDAP service

To perform a query for all the objects within a particular LDAP server which allows unauthenticated queries:

ldapsearch -xLLL -H ldap://myldap.acme.org:389 -b "OU=MyUsers,DC=acme,DC=org"

The arguments are:

-x use simple authentication, not SASL
-LLL return industry-standard extended LDIF without stating the version and without including comments
-H <url> the protocol scheme, hostname, and port to send the request to
-b <scope> the location in the server’s LDAP tree for where to begin any search, the “base DN”

A typical and truncated ldapsearch response (to an OpenLDAP server) will look like:

dn: uid=bmiller,ou=MyUsers,dc=acme,dc=org
facsimileTelephoneNumber: NA
mail: brian.miller@acme.org
telephoneNumber: 555-555-5555
ou: Operations
ou: MyUsers
gidNumber: 1000
roomNumber: -
cn: Brian Miller
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: posixAccount
objectClass: top
homeDirectory: /home/bmiller
givenName: Brian
uid: bmiller
sn: Miller
l: City, State, USA
uidNumber: 10007

Notice here that:

the particular attributes which are returned will vary depending on the vendor of the LDAP service
the simple utility verifies that the specified LDAP server is reachable at the specified port
the LDAP server does not require the DN and password of an administrator account, many do require those

Tip: How to search an open, Secure LDAP server

To perform a query for all the objects within a particular Secure LDAP server which allows unauthenticated queries:

ldapsearch -xLLL -H ldaps://myldap.acme.org:636 -b "OU=MyUsers,DC=acme,DC=org"

The arguments are:

-x use simple authentication, not SASL
-LLL return industry-standard extended LDIF without stating the version and without including comments
-H <url> the protocol scheme, hostname, and port to send the request to
- and here the protocol is ldaps and the port is 636
-b <scope> the location in the server’s LDAP tree for where to begin any search, the “base DN”

A typical and truncated ldapsearch response (to an OpenLDAP server) will look like:

dn: uid=bmiller,ou=MyUsers,dc=acme,dc=org
facsimileTelephoneNumber: NA
mail: brian.miller@acme.org
telephoneNumber: 555-555-5555
ou: Operations
ou: MyUsers
gidNumber: 1000
roomNumber: -
cn: Brian Miller
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: posixAccount
objectClass: top
homeDirectory: /home/bmiller
givenName: Brian
uid: bmiller
sn: Miller
l: City, State, USA
uidNumber: 10007

Notice here that:

the particular attributes which are returned will vary depending on the vendor of the LDAP service
the simple utility verifies that the specified LDAP server is reachable at the specified port and that the client and the server negotiated a secure TLS session using credentials and cypher algorithms that are acceptable to both parties
the LDAP server does not require the DN and password of an administrator account, many do require those

Tip: How to search a restricted, Secure LDAP server

To perform a query for all the objects within a particular Secure LDAP server which requires authenticated queries:

ldapsearch -xLLL -H ldaps://myldap.acme.org:636 -b "OU=MyUsers,DC=acme,DC=org" -D "ldap-admin@acme.org" -w SupremeBeing

The arguments are:

-x use simple authentication, not SASL
-LLL return industry-standard extended LDIF without stating the version and without including comments
-H <url> the protocol scheme, hostname, and port to send the request to
- and here the protocol is ldaps and the port is 636
-b <scope> the location in the server’s LDAP tree for where to begin any search, the “base DN”
-D <admin> the user identifier for the administrator account
-w <passphrase> the plaintext of the administrator’s password

A typical and truncated ldapsearch response (to an OpenLDAP server) will look like:

dn: uid=bmiller,ou=MyUsers,dc=acme,dc=org
facsimileTelephoneNumber: NA
mail: brian.miller@acme.org
telephoneNumber: 555-555-5555
ou: Operations
ou: MyUsers
gidNumber: 1000
roomNumber: -
cn: Brian Miller
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: posixAccount
objectClass: top
homeDirectory: /home/bmiller
givenName: Brian
uid: bmiller
sn: Miller
l: City, State, USA
uidNumber: 10007

Notice here that:

the particular attributes which are returned will vary depending on the vendor of the LDAP service
the simple utility verifies that the specified LDAP server is reachable at the specified port and that the client and the server negotiated a secure TLS session using credentials and cypher algorithms that are acceptable to both parties
the LDAP server does require the DN and password of an administrator account, some do not require those
although the protocol uses SSL, by the time the client utility ldapsearch displays results to the screen, that encryption has been decrypted. The LDIF results are shown in decrypted plain text.

Tip: Compare Configuration attempts with this real-world Example

At Intercax, we use OpenLDAP servers as the delegated Identity Providers for our internal Syndeia deployments. We use open-source Apache Directory Studio to help us provision those LDAP servers.

We are a small company and so we don’t have many users and many groups but our LDAP structure does represent what does occur in larger organizations: there are more corporate users than there are users permitted to log into Syndeia and the users who are permitted to login into Syndeia are limited to those who have been added in the LDAP IdP as members of a specific group.

The screen here shows our LDAP structure.

At the root of the LDAP tree is a base Designated Node for the company. DN: dc=intercax,dc=com

Within the company DN is an Organizational Unit (OU) node that holds all the users, the Organizational Persons. DN: ou=Users,dc=intercax,dc=com

Also within the company DN is a node that holds all the groups or teams within the company. DN: ou=Groups,dc=intercax,dc=com

Within the Users OU are separate entries for each individual and these have three key properties:

The name of the attribute used as the unique identifier. uid
The name of the attribute used to store the person’s unique email address. mail
The DN of each entry. DN: uid=lvanzandt,ou=Users,dc=intercax,dc=com

Within the Groups OU are separate entries for each team and these have four key properties:

The name of the attribute used as the unique identifier. cn
The name of the attribute used to store a reference to a member of the group. uniqueMember
The DN of each entry. DN: cn=SyndeiaUsers,ou=Groups,dc=intercax,dc=com
An attribute or objectClass that identifies that the OU is a group. ou=groups

Note that groups can be nested. Syndeia allows users to be specified in one chosen group; it does not support searching for users who collectively come from separate groups which do not share a common outer group.

Sample silhouette.conf for the Intercax example LDAP

Given an LDAP server such as described here, which responds appropriately to attempted ldapsearch queries, and which is available at the URL ldaps://myldap.acme.org:636, then the following silhouette.conf LDAP setting properties are used:

# LDAP provider
# The values for hostname, baseDN and adminUserDN are placeholder values.
# Please provide actual values, and the value for adminPassword, before using an LDAP provider.
ldap.hostname="myldap.acme.org"
ldap.port=636
ldap.baseDN="dc=intercax,dc=com"
ldap.adminUserDN="cn=admin,dc=intercax,dc=com"
ldap.adminPassword="ShhItIsSecret"
ldap.userBindAttribute="uid"
ldap.startTLS=true
ldap.trustAllCertificates=true
ldap.mailAttribute="mail"

# we limit Syndeia to only those users in the SyndeiaUsers team so:
ldap.groupSettings.dn="ou=Groups,dc=intercax,dc=com"
ldap.groupSettings.ou="groups"
ldap.groupSettings.name="SyndeiaUsers"
ldap.groupSettings.bindAttribute="cn"
ldap.groupSettings.memberAttribute="uniqueMember"

When there is intentional or errant customization of the silhouette.conf file and its ldap properties, Syndeia won't be able to delegate identity authorization requests to the intended LDAP server and users will not be able to authenticate into Syndeia with their accurate (or flawed) LDAP credentials.

Consult the CentOS documentation for details on how CentOS operates and for additional commands to reverse changes made, to make additional changes, or to configure LDAP searches for systems other than Syndeia.