LDAP Overview & Debugging
LDAP Diagram
Sometimes, we might not have detailed instructions for your specific LDAP integration. We've provided here a generalized set of instructions for configuring an LDAP integration and debugging any potential problems.
LDAP Basics
LDAP is a protocol for applications to integrate directory data from a centrally hosted database. The two main actions for applications that connect to LDAP are bind and search. Bind is used to authenticate access to the database and can be done for individual users or through a generic binder account. Search is a customizable way to get the directory data for users and/or groups.
Your application may integrate with Foxpass in one of two ways. Most applications and servers establish an initial connection by binding with an anonymous LDAP Binder and then performing a search to get a list of users and groups. If the application also authenticates users via password, it will then perform a bind with the specific user account to test the user's password. Other applications, like SSH key based logins, will then use an alternative method of authentication.
An LDAP directory uses a tree-based structure, with users on one side and groups on the other. When performing a search on an LDAP database, there are numerous ways to customize and restrict your search to specific variables, attributes, and group memberships.
Configuring the Connection
Most LDAP integrations will follow a similar pattern. First, you'll create an LDAP Binder. Next, you'll configure your application using the binder credentials and Foxpass server values. Finally, you'll test it out to make sure it's behaving as appropriate.
There are some universal settings that most all LDAP connections to Foxpass will use.
LDAP URI: ldap.foxpass.com
Port: 636
Connection type: OpenLDAP
Use SSL (also known as TLS sometimes)
Username: cn=<LDAP binder name>,dc=<example>,dc=<com>
Password: <LDAP binder password>
Your application might also need SSL certificates in order to connect with Foxpass. You can run this commands to get our certificate information:
openssl s_client -showcerts -connect ldap.foxpass.com:636
You can download the root CA at this link.
What is an LDAP binder?
An LDAP binder is a way of integrating an application with an LDAP directory and functions similarly to an API key. You can use a binder to authenticate and bind into the directory, but it isn't represented as an entry within the directory. It's useful to create a binder for each application to help control connections to your directory. That way, you can segregate and classify connections and don't run the risk of losing an integration if a user account is disabled or changes passwords. You can create an LDAP binder and get its Bind DN from the LDAP Binders page.
Example Connection
You can run a test connection from your command line that will establish the validity of your credentials as well as allow you to manually examine your directory data.
ldapsearch -H ldaps://ldap.foxpass.com -b dc=<example>,dc=<com> -D cn=<LDAP binder name>,dc=<example>,dc=<com> -w <binder password>
ldapsearch -H ldaps://ldap.foxpass.com -b dc=<example>,dc=<com> -D uid=<username>,dc=<example>,dc=<com> -w <user password>
This will return a full list of the objects in your directory. An example response with users and groups is provided below. Note that some users and groups have posixUser or posixGroup attributes listed as well as uid and gid numbers. These are required for access to POSIX based systems, like macOS or Linux logins. It's also helpful to look at what attribute names are matched up to what values. For instance, a user's first name is under the 'gn' attribute.
ldap_bind: Success (0)
matched DN: cn=example-binder,dc=foxpass,dc=com
# extended LDIF
#
# LDAPv3
# base <dc=foxpass,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
# foxpass.com
dn: dc=foxpass,dc=com
objectClass: organization
objectClass: top
# people, foxpass.com
dn: ou=people,dc=foxpass,dc=com
objectClass: organizationalunit
objectClass: top
ou: people
description: People from foxpass.com
# christine, people, foxpass.com
dn: uid=christine,ou=people,dc=foxpass,dc=com
cn: Christine Salas
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
memberOf: cn=accounting,ou=groups,dc=foxpass,dc=com
memberOf: cn=sales,ou=groups,dc=foxpass,dc=com
entryUUID: 1940a925-6ced-4e1d-8fef-7efbb296e21c
apple-generateduid: 1940A925-6CED-4E1D-8FEF-7EFBB296E21C
sn: Salas
gn: Christine
mail: [email protected]
modifyTimestamp: 20190321222502Z
uid: christine
# aren, people, foxpass.com
dn: uid=aren,ou=people,dc=foxpass,dc=com
cn: Aren Sarver
memberOf: cn=accounting,ou=groups,dc=foxpass,dc=com
memberOf: cn=eng,ou=groups,dc=foxpass,dc=com
memberOf: cn=founders,ou=groups,dc=foxpass,dc=com
memberOf: cn=root,ou=groups,dc=foxpass,dc=com
memberOf: cn=webmaster,ou=groups,dc=foxpass,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: posixAccount
objectClass: top
loginShell: /bin/bash
entryUUID: 3f3bacd0-c941-4e4f-ba28-254e7d66c16b
apple-generateduid: 3F3BACD0-C941-4E4F-BA28-254E7D66C16B
gidNumber: 100
sn: Sarver
homeDirectory: /home/aren
mail: [email protected]
gn: Aren
uidNumber: 1021
modifyTimestamp: 20190321222432Z
uid: aren
# travist, people, foxpass.com
dn: uid=travist,ou=people,dc=foxpass,dc=com
cn: Travis Thompson
memberOf: cn=root,ou=groups,dc=foxpass,dc=com
memberOf: cn=webmaster,ou=groups,dc=foxpass,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
loginShell: /bin/bash
entryUUID: bb2e57a3-f7da-4615-a020-05b77657ce1c
apple-generateduid: BB2E57A3-F7DA-4615-A020-05B77657CE1C
sn: Thompson
mail: [email protected]
gn: Travis
modifyTimestamp: 20190321222526Z
uid: travist
# richard, people, foxpass.com
dn: uid=richard,ou=people,dc=foxpass,dc=com
cn: Richard Ochs
memberOf: cn=eng,ou=groups,dc=foxpass,dc=com
memberOf: cn=root,ou=groups,dc=foxpass,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: posixAccount
objectClass: top
loginShell: /bin/bash
entryUUID: fcea2382-1657-44d0-960e-d9e15aca8a44
apple-generateduid: FCEA2382-1657-44D0-960E-D9E15ACA8A44
gidNumber: 100
sn: Ochs
homeDirectory: /home/richard
mail: [email protected]
gn: Richard
uidNumber: 1054
modifyTimestamp: 20190321222510Z
uid: richard
# groups, foxpass.com
dn: ou=groups,dc=foxpass,dc=com
objectClass: organizationalunit
objectClass: top
ou: groups
description: Groups from foxpass.com
# sales, groups, foxpass.com
dn: cn=sales,ou=groups,dc=foxpass,dc=com
member: uid=christine,ou=people,dc=foxpass,dc=com
cn: sales
objectClass: groupOfNames
entryUUID: 782c5c4a-8e30-4cc2-8ec5-2e2a735a5f80
apple-generateduid: 782C5C4A-8E30-4CC2-8EC5-2E2A735A5F80
modifyTimestamp: 20190318232818Z
# accounting, groups, foxpass.com
dn: cn=accounting,ou=groups,dc=foxpass,dc=com
member: uid=aren,ou=people,dc=foxpass,dc=com
member: uid=christine,ou=people,dc=foxpass,dc=com
cn: accounting
objectClass: groupOfNames
entryUUID: 45fbd8bb-fdaf-4726-b200-14fb37fa2f0b
apple-generateduid: 45FBD8BB-FDAF-4726-B200-14FB37FA2F0B
modifyTimestamp: 20190318232817Z
# founders, groups, foxpass.com
dn: cn=founders,ou=groups,dc=foxpass,dc=com
member: uid=aren,ou=people,dc=foxpass,dc=com
cn: founders
objectClass: groupOfNames
objectClass: posixGroup
memberUid: aren
entryUUID: c5f89ea3-8b10-447a-ab9d-28973b6d4c36
apple-generateduid: C5F89EA3-8B10-447A-AB9D-28973B6D4C36
gidNumber: 725
modifyTimestamp: 20190321223635Z
# webmaster, groups, foxpass.com
dn: cn=webmaster,ou=groups,dc=foxpass,dc=com
member: uid=aren,ou=people,dc=foxpass,dc=com
member: uid=travist,ou=people,dc=foxpass,dc=com
cn: webmaster
objectClass: groupOfNames
entryUUID: 9b035866-a56a-4096-aa25-a971566be562
apple-generateduid: 9B035866-A56A-4096-AA25-A971566BE562
modifyTimestamp: 20190318232818Z
# eng, groups, foxpass.com
dn: cn=eng,ou=groups,dc=foxpass,dc=com
member: uid=aren,ou=people,dc=foxpass,dc=com
member: uid=richard,ou=people,dc=foxpass,dc=com
cn: eng
objectClass: groupOfNames
objectClass: posixGroup
memberUid: aren
memberUid: richard
entryUUID: 71fb71e3-a3a7-455b-a7c0-c39289e70f77
apple-generateduid: 71FB71E3-A3A7-455B-A7C0-C39289E70F77
gidNumber: 724
modifyTimestamp: 20190321223631Z
# root, groups, foxpass.com
dn: cn=root,ou=groups,dc=foxpass,dc=com
member: uid=aren,ou=people,dc=foxpass,dc=com
member: uid=richard,ou=people,dc=foxpass,dc=com
member: uid=travist,ou=people,dc=foxpass,dc=com
cn: root
objectClass: groupOfNames
entryUUID: 99c63cba-0956-4358-b824-f2a68f66a54f
apple-generateduid: 99C63CBA-0956-4358-B824-F2A68F66A54F
modifyTimestamp: 20190318232818Z
You can see all the information and various identifiers associated with each object, as well as the bidirectional group membership association. There are many other attributes that can be returned, contact us if you need more data in your LDAP schema.
Debugging & Troubleshooting
Your basic debugging process will go something like this:
- Test the connection. Try testing or logging into your application. This will generate a request from your application to Foxpass.
- Check our LDAP logs. If you don't see the request in the LDAP logs, then there's something wrong with your configuration. Double check that your configuration is correct and test the connection again. Your firewall also might also be blocking the connection. If you do see the request, check to see what the error is.
- Check your password. Make sure that you're using the correct password. We'll note in the logs what data source we are checking against as to whether it's local (Foxpass) or remote (Third Party). All binders will use their generated Foxpass password.
- Check your attribute mappings. If you're seeing a successful bind, but group memberships or other user data isn't showing up, you might have an issue with your search attributes. Run an example ldapsearch command to see what an LDAP search response looks like from Foxpass, or just consult the example below. If you can't figure out what data corresponds to which attributes or are otherwise confused, contact us at [email protected] or over Intercom chat via the blue icon in the bottom right hand corner and we can check your requests on our backend logs.
Updated 14 days ago