JumpCloud's LDAP authentication

This section describes how to configure Heimdall Proxy's LDAP authentication to work with JumpCloud's LDAP implementation.

Remember that for easy checking if configuration works in your environment, you can use "Authentication Test" in "Proxy Configuration" in Virtual DB configuration tab. By providing only a username and password, you can check if your actual configuration works and users can be authenticated as you expect. Other details, like IP address, database or using SSL, aren't needed to be filled to do a test for LDAP authentication mode.

Prerequisites

At the beginning, we will describe the JumpCloud LDAP configuration which will be used in this section. First part is setting users. As can be seen on the below screenshot, we have four users - example_admin, example_user_1, example_user_2 and example_user_3.

First user - example_admin has a details as shown below. Please notice that username is different from first name. Username of the user is admin and that name determines LDAP Distinguished Name.

User example_admin will be used for performing bind and search operations in JumpCloud LDAP, so we have to give that user a permission to do that, as shown below.

We need to be sure that the user belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

The next user, example_user_1, has a details as shown below.

We need to be sure that the user belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

The next user, example_user_2, has a details as shown below.

We need to be sure that the user belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

The next user, example_user_3, has a details as shown below.

We need to be sure that the user belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

Next step of configuration is defining groups. For cases described here, three groups will be needed - example_group_1, example_group_2 and example_group_3, as shown below.

First group is example_group_1. The group has only one member, which is example_user_1, as shown below.

We need to be sure that the group belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

Next group is example_group_2. The group has only one member, which is example_user_2, as shown below.

We need to be sure that the group belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

Next group is example_group_3. The group has only one member, which is example_user_3, as shown below.

We need to be sure that the group belong to the JumpCloud LDAP directory, as shown below, to use it during authentication.

More information about our objects can be retrieved by using tool named ldapsearch. By using the below line, the search will be done with:

• simple authentication instead of SASL (-x)
• using uid=admin,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com user as Distinguished Name to bind to LDAP directory (-D "uid=admin,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com")
• with a prompt for simple authentication, instead specifying the password on the command line (-W)
• with URI specified to ldap://ldap.jumpcloud.com:389 (-H ldap://ldap.jumpcloud.com:389)
• with searchbase ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com (-b ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com)
• with scope set to subtree (-s sub)

ldapsearch -x -D "uid=admin,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com" -W -H ldap://ldap.jumpcloud.com:389 -b "ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com" -s sub   

Information about objects will give us details about attributes of each object. That information will be helpful during configuration of authentication.

Details about user example_user_1 are as shown below.

# example_user_1, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: uid=example_user_1,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: shadowAccount
objectClass: posixAccount
objectClass: jumpcloudUser
uid: example_user_1
uidNumber: 5003
homeDirectory: /home/example_user_1
mail: example+1@heimdalldata.com
sn: example_user_1
gidNumber: 5003
loginShell: /bin/bash
givenName: example_user_1
cn: example_user_1
displayName: example_user_1
memberOf: cn=example_group_1,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Details about user example_user_2 are as shown below.

# example_user_2, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: uid=example_user_2,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
uidNumber: 5004
homeDirectory: /home/example_user_2
mail: example+2@heimdalldata.com
givenName: example_user_2
sn: example_user_2
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: shadowAccount
objectClass: posixAccount
objectClass: jumpcloudUser
uid: example_user_2
gidNumber: 5004
loginShell: /bin/bash
cn: example_user_2
displayName: example_user_2
memberOf: cn=example_group_2,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Details about user example_user_3 are as shown below.

# example_user_3, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: uid=example_user_3,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
displayName: example_user_3
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: shadowAccount
objectClass: posixAccount
objectClass: jumpcloudUser
uidNumber: 5005
gidNumber: 5005
mail: example+3@heimdalldata.com
givenName: example_user_3
uid: example_user_3
loginShell: /bin/bash
homeDirectory: /home/example_user_3
sn: example_user_3
cn: example_user_3
memberOf: cn=example_group_3,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Details about group example_group_1 are as shown below.

# example_group_1, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: cn=example_group_1,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
ou: example_group_1
objectClass: top
objectClass: groupOfNames
description: tagGroup
cn: example_group_1
member: uid=example_user_1,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Details about group example_group_2 are as shown below.

# example_group_2, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: cn=example_group_2,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
cn: example_group_2
ou: example_group_2
objectClass: top
objectClass: groupOfNames
description: tagGroup
member: uid=example_user_2,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Details about group example_group_3 are as shown below.

# example_group_3, Users, 60d43f001430a71e78154864, jumpcloud.com
dn: cn=example_group_3,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com
cn: example_group_3
ou: example_group_3
objectClass: top
objectClass: groupOfNames
description: tagGroup
member: uid=example_user_3,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com

Simple user authentication

To begin, let's assume that we want to give access to all users, which we defined in JumpCloud's LDAP. Additionally, we don't care if a user belong to a group or not. In this case, on the Heimdall Proxy's side, to authenticate a user, without looking at groups to which the user belongs, the best is LDAP Simple Mode authentication. An example of configuration to set proper authentication can be seen below.

As can be seen, the configuration specifies only two values: LDAP Prefix and LDAP Suffix. Both of them, with username of a user connecting to a proxy, will build a string, which is going to be used to connect to a JumpCloud LDAP. That single step is enough to perform an authentication in Simple Mode.

With above configuration, all users, so example_user_1, example_user_2 and example_user_3, will be authenticated successfully (assuming that proper credentials, so username and password, were given).

Authenticating user from a group

A more complex case than previous one, would be a situation, when we care if a user belong to a group, but we don't care what group it is. For that situation the best will be LDAP Bind+Search Mode authentication without a group filter. An example of configuration to set proper authentication can be seen below.

The configuration for Bind+Search Mode is more complex than for Simple Mode, so we are going to explain each property.

LDAP property	Value	Explanation
LDAP(S) URL	ldap://ldap.jumpcloud.com:389	Specifies URL of JumpCloud LDAP. In the example specified to a port without using SSL, but can be configured to an address using it.
LDAP Security Principal	uid=admin,ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com	Specifies user with enabled bind and search in JumpCloud LDAP service. For our case, it is a LDAP Distinguished Name of example_admin user.
LDAP Search User Password	(hidden)	Specifies password to authenticate as user specified in LDAP Security Principal. For our case, it is a password for example_admin user.
LDAP Search Domain	o=60d43f001430a71e78154864,dc=jumpcloud,dc=com	Specifies domain in which a user's group will be searched for. For our case, the value is as shown, without declaring any ou, because search will be done with subtree scope.
LDAP User Search Base	ou=Users,o=60d43f001430a71e78154864,dc=jumpcloud,dc=com	Specifies base for searching a user to be authenticated. For our case, the value is as shown, with declaring ou as Users, because we will be looking for users.
LDAP Name Attribute	uid	Specifies attribute, which should be used to identify a user, so if value of the attribute is equal to a username connecting to a proxy. The value for our case is based on reads for users objects from ldapsearch results.
LDAP Group Name Attribute	cn	Specifies attribute, which should be used to extract information about a group, so the name of a group. For our case, we read from ldapsearch results that objects of group don't have uuid attribute, so we need to specify a different one. From ldapsearch result can be read, that cn value is unique for our groups, so we are going to use it to authenticate them.
LDAP Group Filter	(empty)	Specifies group filter, which will be added during a search for a user's groups. For this example we don't need to specify it. When this attribute is specified, filter is added during searching for a user's groups and the filter can specify what restrictions have to be met by a group, e.g. value of an attribute of a group object.
Use nested groups filter	false	At the time of writing this section (8th July 2021), JumpCloud LDAP doesn't handle nested groups, so that option have to be turned off, because turned on can break authentication and return no results.

With above configuration, all users, so example_user_1, example_user_2 and example_user_3, will be authenticated successfully (assuming that proper credentials, so username and password, were given). That will happen, because all of these users belongs to groups (user example_user_1 is in group example_group_1, user example_user_2 is in group example_group_2, user example_user_3 is in group example_group_3). If there was a user without a group, that user would be rejected by authentication.

Authenticating user from a specified group

The most complex is when we want only to authenticate users from particular groups. First, let's assume that we only want to authenticate users from example_group_1 group. For that situation the best will be to use LDAP Bind+Search Mode authentication with a group filter. An example of the configuration to accept users only from example_group_1 group, can be seen below.

The configuration differs from a previous one by set value of LDAP Group Filter which specifies what value of cn attribute a group must have. Based on details read by using ldapsearch before, we know that cn value is unique between groups, so can be used for authenticating them. For example_group_1 group, that value is example_group_1, so that's why group filter is (cn=example_group_1). Using that configuration, only user example_user_1 will be authenticated (assuming that proper credentials, so username and password, were given). For user example_user_2 and example_user_3 authentication will end up with a failure, during checking their groups.

Next situation is when we want to authenticate users from example_group_1 or example_group_2. With that case we want to be sure that a user belong to any of these groups two groups. An example of configuration to accept users only from example_group_1 or example_group_2 group, can be seen below.

Again, the only change is in value of LDAP Group Filter. Set filter specifies that cn value of a group has to match example_group_1 or example_group_2, so only groups with these values will be used, and that mean that only users from these groups will be authenticated. For our case, only example_user_1 and example_user_2 will be authenticated (assuming that proper credentials, so username and password, were given). For user example_user_3 authentication will end up with a failure, during checking their groups.

The example of the LDAP Group Filter can be extended to set restrictions on more arguments as needed. The main rule is that filter has to met requirements of LDAP filters used to search. The second rule is that group filter has to be in brackets. If group filter exists, is joined, by using AND operator, to filter checking if a user is a member of a group.