探花大神

探花大神鈥檚 Directory-as-a-Service solution is based in large part on LDAP. A core part of the solution is to enable devices and applications to authenticate via LDAP. The way our solution works is that admins place their users in the 探花大神 directory. Our directory enables those credentials that have been created in the 探花大神 directory to be leveraged via a number of different protocols such LDAP, SAML, SSH, and others. The goal of Directory-as-a-Service is to enable a wide variety of devices and applications to be authenticated and authorized.

For this particular blog post, we鈥檒l focus on the ability for applications to authenticate to our LDAP server. The process generally works as follows:

1. Users are created within 探花大神
2. To authenticate/authorize via LDAP, you enable the LDAP setting in 探花大神
3. You configure your application to connect and authenticate/authorize to the 探花大神 LDAP server
4. An end user types in their credentials in the application
5. The application authenticates and authorizes to 探花大神鈥檚 LDAP endpoint
6. The user is granted the proper permissions

The core of this process is how to configure your application to communicate with 探花大神. This can be a tricky configuration setup if you don鈥檛 know the various parameters to pass to LDAP. We鈥檒l review some of those parameters here, but, of course, if you need help connecting your application to 探花大神, just drop us a note 鈥� we鈥檇 be happy to help.

We鈥檝e already blogged about connecting a number of common applications to 探花大神. These include: Git LDAP authentication, Okta, OpenVPN, Meraki, Jira, Confluence, and MySQL LDAP configurations among others. These are good examples and will provide you with a variety of different approaches to connecting your application to LDAP.

For your specific application, we鈥檒l go over some of the key parameters to consider:

• Hostname or IP address 鈥� you鈥檒l need to configure the 探花大神 hostname or IP address for your application to connect to 探花大神. With 探花大神, this is 鈥渓dap.jumpcloud.com鈥�
• Port 鈥� you鈥檒l want to specify the port that you would like to go over to 探花大神. We use two ports 鈥� 389 and 636. Port 636 is reserved for LDAPS, while 389 supports either clear text communications or STARTTLS.
• Encryption approach 鈥� you鈥檒l want to specify whether you are using SSL, STARTTLS, or clear text. Because LDAP encryption is up to the client, and not the server, we recommend that you use STARTTLS whenever possible (LDAPS, or LDAP over SSL, is deprecated, though still frequently supported by clients and servers, including 探花大神). Using cleartext for initial setup and troubleshooting can be very helpful, but for production, STARTTLS is preferred (use port 389 with STARTTLS enabled in your client).

Binding

Field names for applications include: Bind DN, Manager DN, Password
In LDAP, authenticating your user is called 鈥渂inding鈥� to the directory. With a bind, you provide your username and password to the LDAP server. There are three potential outcomes: 

1. Your username and password are not recognized. This results in an authentication failure (you can鈥檛 go any further, nor do you know any more about the user than when you started).
2. Your username and password are recognized, but the user has no further permissions on the LDAP server. You know from this that the user has provided correct credentials, so you can (reasonably) trust that they are who they say they are, but they can鈥檛 do anything further with the directory itself. Most of your user accounts should fall into this category.
3. Your username and password are recognized, and the user has additional permissions to read and/or write objects in the directory. 探花大神 calls this type of user an 鈥�.鈥� Users with this level of permission can search the remainder of the directory. They are able to look at all the users in the 探花大神 account, as well as their tag and POSIX group membership. You鈥檒l use this type of user account for your applications to look up group membership, enumerate users, or to be able to use the LDAP directory for application or system-wide authentication and authorization.

Because LDAP is a directory database, and not simply a user store, it鈥檚 a bit more complicated to specify your username than with a simple user store. LDAP is a hierarchical database, which means that you need to provide a full path to your user object. A username in isolation won鈥檛 be enough information for LDAP to identify which user object you鈥檙e talking about.

In 探花大神 you specify a user in the following format:

uid=<username>,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com

for example:

uid=jdoe,ou=Users,o=309AF39093AFBBDCF902093015672309,dc=jumpcloud,dc=com

The directory structure is read from right to left:

• That is, dc=com is the top of the directory tree, and potentially multiple dc objects can be found beneath it. With 探花大神鈥檚 hosted LDAP service, only one dc object exists within 鈥渃om鈥�, and that is 鈥渄c=jumpcloud鈥�. The abbreviation, 鈥渄c鈥�, stands for domain component, and is meant to identify an organizational domain.
• Next, o=<organizationId> uniquely identifies your part of the 探花大神 LDAP directory. It鈥檚 how 探花大神 partitions and isolates user account data from one customer to the next – fully and securely.
• 鈥渙u=Users鈥� specifies the 鈥渙rganizational unit鈥�, which is a fancy term for a container of multiple objects. All objects in the 探花大神 hosted LDAP service can be found in the Users OU, which includes user objects, group objects, and POSIX group objects.
• Finally, uid specifies the username in your Users OU. This username is what you would commonly think of as the username that you would type in along with your password.

The string above, 鈥渦id=<username>,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com鈥� is called a 鈥淒N鈥� or distinguished name, because it uniquely identifies an object in the LDAP directory structure.

So when you bind to 探花大神鈥檚 LDAP directory, instead of username and password, you really provide a DN and password for authentication. Some applications only try to bind to LDAP to perform authentication, while others bind and then search. Those that bind and search require an LDAP Binding User Service Account for the DN, while the others do not.

Searching

Field names for applications include: Search Base, Group Name, User Name, Base DN

Assuming that a bind has taken place with an LDAP Binding User Service Account, let鈥檚 consider the three types of objects that you can search:

1. Users: A user is an object (really based on an object type called InetOrgPerson) which contains all the details for a given user in your directory. 探花大神 also provides the 鈥渕emberOf overlay鈥�, which means that each user contains the list of groups of which it is a member, which some client applications require to determine group membership.
2. Groups: 探花大神 LDAP provides 鈥済roupsOfNames鈥� objects which contains DNs for all users that are selected within a 探花大神 Tag. This allows you to use a Tag as a way to specify roles and access authorization for any number of users or any number of applications. It鈥檚 always up to the application to assign meaning to being a member of a group, such as 鈥淎dministrators鈥�, 鈥淲iFi Users鈥�, or 鈥淚nternal App Users鈥�.
3. POSIX Groups: POSIX groups reflect the attributes necessary to create a group on a Linux or OS X server, including a POSIX compliant group name, group ID, and users who are members of the group. It is this type of object that allows you to cause LDAP client operating systems, such as Linux, to be able to determine operating system-level group membership.

Because LDAP鈥檚 directory is freeform, many applications have to ask you for the path where they can find each of the above types of objects (normally they only ask about Users and Groups, however). This is referred to as the Search Base, the place where the client application expects to search and find that type of object. Some applications expect a single search base (which is similar to how Active Directory is structured), while others know that User and Group objects may be in different directory locations.

Your answer to this question for either Users or Groups is the same:

ou=Users,o=<organizationId>,dc=jumpcloud,dc=com

This is because that DN includes all three object types. That value is what you鈥檒l use for your search base, or base DN value.

When an application requests user unique identifier, you鈥檒l generally want to use:

uid

A uid value, followed by the rest of the search base, will uniquely identify any user object in your 探花大神 LDAP directory, for example:

uid=jdoe,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com,

When an application requests group unique identifier, you鈥檒l generally use:

cn

鈥淐N鈥� stands for Common Name, and is the way a 探花大神 group is identified. For example:

cn=WiFi Users,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com

This will uniquely identify the 鈥淲iFi Users鈥� group in your 探花大神 LDAP directory.

Filtering

Because it is up to the client application to bring meaning to the LDAP directory, the client chooses which groups are meaningful to it. For example, if you鈥檙e running OpenVPN and using 探花大神 to authenticate user logins, you may only want to allow members of the 鈥淐hicago OpenVPN Users鈥� group to be able to login using the VPN.

To do that, you鈥檒l need to filter your set of users down to only those that are members of 鈥淐hicago OpenVPN Users鈥�, and to do that, we鈥檒l need to use a filter.

Groups-First Filter

In some cases, an application will allow you to specify a group DN and will be able to query all the members of that group. In these cases, you鈥檒l simply provide the DN of your group, such as:

cn=Chicago OpenVPN Users,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com

The application can then query all the member attributes of the 鈥淐hicago OpenVPN Users鈥� group, which will look like:

member: uid=jdoe,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com
member: uid=pembroke,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com
member: uid=jody,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com

The application can then use this list to determine whether to allow the to login, or not.

MemberOf Filter

Since the 探花大神 LDAP service supports the memberOf overlay, each user also contains the list of all the groups of which it is a member.

In this case, the search is a bit different, you鈥檒l specify a filter that returns only the members of a particular group. A filter for our OpenVPN group would look like:

(&(objectType=inetOrgPerson)(memberOf=cn=Chicago OpenVPN Users,ou=Users,o=<organizationId>,dc=jumpcloud,dc=com))

This filter says, return me all the objects with an objectType of inetOrgPerson (a User), that are also a member of the 鈥淐hicago OpenVPN Users鈥� group.

Other Filters

Filters can be very complex, but this filter is one that is very common. You can also build filters that search for only a specific group. For example:

(&(objectClass=groupOfNames)(cn=Admins))

This filter will return only group objects named 鈥淎dmins鈥�. For more details around using filters, please see our knowledge base article on the topic.

Need More Help?

These are the most common settings that you鈥檒l need when connecting your application to 探花大神鈥檚 hosted LDAP solution. Of course, there may be more nuances depending upon the application, but this should get you started. If you need further help, drop our support line a note and they would be happy to help.