Skip to content

LDAP Authentication and User Synchronization

Before you start

Goal

  • Connect Altair SLC Hub to an LDAP server to import user information from the LDAP database into the Hub user database and to allow end user authentication.

Prerequisites

At a minimum, the following information about the LDAP server is required:

  • The hostname and port number of the LDAP server.
  • The LDAP Distinguished Name (DN) and bind credentials of an LDAP user that can be used to perform queries against the LDAP server. It is advised that this user only has readonly access to the LDAP server.
  • The base Distinguished Name (DN) for the LDAP directory (the hubctl command that can assist in retrieving this if it is not known).

Further configuration information may be required, depending on the individual circumstances.

Basic Configuration

The configuration settings related to LDAP are contained in the [etc directory]/config.d/auth_ldap.yaml configuration file.

Do not modify the auth_ldap.yaml file. If any settings need changing, take a copy of the file and save it to a file in the same directory with a lexicographically greater name. For example, save the copy as [etc directory]/config.d/auth_ldap_custom.yaml.

Initially, the following settings are required:

  • host
  • bindDN
  • bindPassword
  • bindPasswordEncoding
  • searchBase
  • schema

host

Specifies the hostname of the LDAP server and optionally the port number.

If no port is provided the default secure LDAP port of 636 is used.

By default, Altair SLC Hub uses the secure ldaps: protocol to communicate with the LDAP server. This is the recommended configuration.

Note

In the case of Microsoft Active Directory, one of two port numbers can be selected: either port 389 or port 3268. Port 3268 returns information from the global catalog, which may not contain all attributes for those entries (not all attributes are marked for replication to the global catalog). Port 389 returns information from the local domain controller only. This is likely to be what is required.

Examples:

host: ldapserver
host: ldapserver.example.com
host: ldapserver.example.com:636

Verify LDAP host name

The host configuration setting can be verified using the following command:

 hubctl verify ldap connection

This will make an anonymous connection to the LDAP server and will indicate whether there are any issues with the hostname, port number or SSL settings.

For testing purposes, the insecureNoSSL configuration setting can be used to make a connection to LDAP without using SSL. This can help to diagnose any SSL problems, but this is not recommended for production.

bindDN

Specifies the LDAP Distinguished Name (DN) of the LDAP principal with which the Hub will bind to LDAP for the purposes of performing queries. It is recommended that a dedicated principal restricted to read access only is used to access the directory.

Example: 

bindDN: cn=readonly,dc=example,dc=com

Altair SLC Hub can be configured to retrieve bind credentials from a Hashicorp Vault instance. It is recommended that, until LDAP settings are finalized, the bind credentials are entered in the configuration file. Once the LDAP settings are finalized, the bind credentials can be moved into Hashicorp Vault as a separate step.

bindPassword

Specifies the password associated with the principal given in the bindDN configuration parameter. This is either supplied in base64 (the default) or in plain text according to the value of the bindPasswordEncoding configuration setting.

Example: 

bindPassword: c2VjcmV0Cg==

bindPasswordEncoding

Specifies wither the bind password is supplied in base64 (the default) or plain text. The value should be one of "base64" or "plain".

Verify LDAP bind credentials

The LDAP bind credentials can be verified using the following command:

hubctl verify ldap bind

This command connects to LDAP and authenticates (binds) using the credentials given in the bindDN and bindPassword settings.

searchBase

Specifies the Distinguished Name (DN) of the point in the LDAP hierarchy from which any LDAP queries are performed. This includes the searches during LDAP user synchronization and the searches when authenticating an end user using LDAP.

At this stage it is recommended to set this to the base DN of the LDAP directory. This can be refined later if necessary.

The hubctl tool can be used to query the LDAP directory for a list of the base DNs for the directory. This is supported on common LDAP directory server software products, including Microsoft Active Directory and OpenLDAP.

To fetch the list of base DNs for the LDAP server, use the following command:

hubctl ldap fetchbasedn

This will produce a list of LDAP distinguished names such as:

DC=example,DC=com
CN=Configuration,DC=example,DC=com
CN=Schema,CN=Configuration,DC=example,DC=com

It is recommended that one of these be used for the search base in the first instance.

Examples:

searchBase: dc=example,dc=com
searchBase: ou=business-unit,dc=example,dc=com

Verify LDAP search base

To verify that the LDAP search base exists use the following command:

hubctl verify ldap searchbase

This connects to LDAP directory and performs a search for the entry specified by the search base configuration parameter.

schema

If the LDAP directory to which the connection is being made is a Microsoft Active Directory server, specify Active Directory for this configuration setting. Otherwise, there is no need to set this.

Refining the LDAP Synchronization Configuration

The first step in refining the configuration is to establish how many users and groups Hub would import with the default LDAP configuration.

To list the number of users that would be imported, run the following command: 

hubctl ldap counthubusers

To list the number of groups that would be imported, run the following command: 

hubctl ldap counthubgroups

These commands will perform the same query that is performed by the LDAP synchronization process and return the number of results.

It is then possible to list the users and groups that are returned to Hub using the hubctl ldap listhubusers and hubctl ldap listhubgroups commands. These commands will list the information returned to the Hub when performing an LDAP query for all users or groups.

To print the list of users that are returned to Hub when performing the LDAP query, run the following command:

hubctl ldap listhubusers

The results are limited to 1000 entries by default. The --limit command line option can be used to specify a different limit.

To print the list of groups that are returned to Hub when performing the LDAP query, run the following command:

hubctl ldap listhubgroups

Results are limited to 1000 entries by default, and the --limit command line option can be used to specify a different limit.

The output from these two commands could show two basic problems: the wrong list of users and groups is returned, or the attributes of the users and groups is not populated correctly.

Verify the right set of users and groups are returned

The first step is to ensure that the correct set of users is being returned. It is also sensible to optimise the LDAP search base for these queries to ensure that they are as efficient as possible whilst still returning the correct set of values.

There are two basic methods to restrict the number of users and groups that are returned:

  • The search base for the query can be changed to point to a lower point in the hierarchy, so that only users within a certain branch of the LDAP hierarchy are imported.

  • A custom LDAP filter can be created that could, for example, ensure only users that are members of a certain group are imported.

This is an iterative process. Having made changes, rerun the hubctl ldap listhubusers and hubctl ldap listhubgroups commands until they return the correct information.

Refine search bases for users and groups

The first method of restricting the list of users and groups that are returned is to provide a value for the usersDN configuration setting and/or the groupsDN configuration setting. These settings should be refined first, so that the base DN of the search is as narrow as possible while still containing all of the required users or groups.

For example, if all of the users to import are known to be in a certain organisational unit in LDAP, specifying that as the usersDN configuration setting will mean only those users are imported. This is also important for efficiency of any searches that are performed. The narrower the LDAP searches can be made, the more efficient any queries will be.

The output of the hubctl ldap listhubusers and hubctl ldap listhubgroups commands will indicate whether a value should be set for the usersDN or groupsDN configuration settings. The distinguished name of each user and group is listed. At the end of the output, the common suffix of any distinguished names is printed and this can be a guide to specifying the usersDN and groupsDN configuration settings. Note that the output may not list all users or groups (it only lists 1000 by default), and the common suffix that is printed is only the common suffix of those entries returned.

Provide custom search filters for listing users and groups

The second method of refining the list of users or groups imported into Hub is to provide custom LDAP search filters with the listAllUsersQuery and listAllGroupsQuery configuration settings.

An example of where this would be used is if the only users that should be imported are those that are a member of a certain group.

The default value for the listAllUsersQuery is (&(objectCategory=person)(objectClass=user)). To return only the users that are a member of a certain group, a query such as the following can be used:

(&(objectCategory=person)(objectClass=user)(memberOf=CN=group-name,DC=example,DC=com))

This adds an extra search term requiring that the returned LDAP entry has a memberOf attribute equal to the value CN=group-name,DC=example,DC=com. The value CN=group-name,DC=example,DC=com is the LDAP distinguished name of the group.

Altair SLC Hub provides some tools that can be used to explore the LDAP directory and establish the distinguished named for entries, see Useful commands to explore the LDAP hierarchy

Verify the attributes of the Hub users and groups are populated

Once the user and group listings contain the correct set of users, it is recommended the hubctl ldap listhubusers and hubctl ldap listhubgroups commands are run to ensure that the attributes of the users and groups returned to Hub are populated correctly.

If some attributes are not populated (for example, email addresses) ensure the schema configuration setting has been set to correctly match the type of the LDAP directory. If this is set correctly, the Hub configuration settings that govern which LDAP attributes are returned will need to be modified.

The output from the hubctl ldap listhubusers and hubctl ldap listhubgroups commands includes the full LDAP Distinguished Name (DN) of the entry from which the user is read. This can be used with the hubctl ldap getentry command to return the raw LDAP entry for that user.

The output from the hubctl ldap getentry command can be compared to the output from the hubctl ldap listhubusers and hubctl ldap listhubgroups commands to see what LDAP attributes are available on the user entry, and adjust the Hub LDAP configuration as required.

More information about the Hub configuration attributes that can be used and their default values can be found in the auth_ldap.yaml configuration file.

Useful commands to explore the LDAP hierarchy

hubctl ldap getentry

The hubctl ldap getentry can be used to return the LDAP attributes of a particular entry, given its LDAP distinguished name.

The hubctl ldap listhubusers and hubctl ldap listhubgroups commands print the distinguished name of any users they return. The DNs of entries are returned by the hubctl ldap search command. These can then be used with the hubctl ldap getentry command.

For example, the hubctl ldap listhubgroups might show a DN of CN=James Watt,OU=Users,DC=example,DC=com. This can then be used with the hubctl ldap getentry command as follows:

hubctl ldap getentry "CN=James Watt,OU=Users,DC=example,DC=com"

Note that it recommended that the DN entry specified in the command is surrounded by quotation marks as often a DN will have spaces or other characters that might otherwise affect the parsing of the command line.

The names of the groups to which a user belongs is typically described in LDAP using the memberOf attribute. LDAP attributes can be multi-valued and each value of the memberOf attribute is the distinguished named of the LDAP entry representing a group. The distinguished names of the groups that a user is a member of are listed in the output created when running the hubctl ldap getentry command.

Note that Microsoft Active Directory also uses the msSFU30PosixMemberOf to represent group members. If using Active Directory, group membership for a user might be in either the memberOf or msSFU30PosixMemberOf attributes.

The hubctl ldap search command can be used to perform arbitrary queries against the LDAP directory and will print the raw LDAP attributes of any entries returned.

There are a number of ways in which this can be used:

  • To look up an entry in the LDAP directory by its "common name".

  • To look up a user in the LDAP directory by the user's logon username

  • To return the list of entries that are directly below a given entry.

  • To verify that a search filter will return the correct contents. for example, when constructing a search filter for use with the listAllUsersQuery Hub configuration parameter.

To find a user or group with a known name, search the LDAP hierarchy for an entry with a given "common name" or cn attribute. The "common name" for a user would be their normal known name; for a group, the "common name" would be the group name. This can be useful to find an LDAP entry from a name such as "James Watt" or a group name "Scientists". This can be done with a command such as the following:

hubctl ldap search "(cn=Scientists)"
hubctl ldap search "(cn=James Watt)"

Note that these search filters do not restrict the type of entry that is returned, they do not restrict the search to only return users or groups for example. These searches may, therefore, return more than one entry.

To find a user by logon username, use a command such as the following:

hubctl ldap search "(sAMAccountName=james_watt)"
hubctl ldap search "(uid=james_watt)"

Whether to search by sAMAccountName or uid depends on the kind of LDAP directory. Microsoft Active Directory uses the sAMAccountName attributes, other directory products generally use the uid attribute. This search mirrors the search carried out by the Hub when a user attempts to log on with that username.

To list all of the entries directly below a given entry in the directory, use a command such as:

hubctl ldap search --scope one --baseDN "dc=example,dc=com"

The option --scope one restricts the results to only those entries that are one level below the specified base DN.

Performing LDAP User Synchronization

Before performing LDAP synchronization, it is recommended a "dry run" test is performed. For example, to perform a dry run test of user synchronization, use the following command

hubctl ldapsync --dryrun

The command prints out a list of the operations that it would have performed. If the LDAP configuration settings are not correct an error is returned.

Assuming that the results of the user synchronization are as expected, the user details can be imported by removing the --dryrun option from the command:

hubctl ldapsync

Verify that the users have been created successfully by looking at the list of users in the Altair SLC Hub portal.

Verify that running the LDAP user synchronization again makes no changes by performing a dry run. It should report no changes need to be made.

Removing external users

It is possible to remove all users that have been created by an LDAP synchronization process. This is intended for use during the initial configuration process to return the system to its initial state. It is not intended to be used during normal production use.

To remove all external users and groups, run the following command:

hubctl removeexternal

Scheduling regular LDAP user synchronization

Having successfully set up LDAP user synchronization, it is recommended that user synchronization is configured to occur regularly.

To create a synchronization schedule, use the cron command or equivalent to run the hubctl ldapsync command.

To create a synchronization schedule, use the Windows Task Scheduler to run the hubctl ldapsync command.

Enabling LDAP Authentication

To enable Hub to use LDAP for authentication for users, it is necessary to set the value of the Hub auth.ldap.enabled configuration setting. Use the hubctl config print command to check the existing setting:

hubctl config print auth.ldap.enabled

If necessary, edit the setting in your copy of the [etc directory]/config.d/auth_ldap.yaml configuration file.

Having changed this setting to enable the LDAP authentication connector, restart the authentication service using the following command:

hubctl service restart auth

Log in to the hub portal from a web browser. It should then be possible to authenticate as one of the users that have been synchronized from LDAP.

Note

At this point, such a user would not have permission to use the portal. A successful test is to log in to the Hub with a user that has been imported from LDAP and to receive a message saying that the user does not have permission to use the Hub.

To be able to use the portal, users need to be a member of the PortalUsers group.

Storing LDAP bind credentials in Hashicorp Vault

Rather than storing the LDAP bind credentials in the Hub configuration files, it is possible to retrieve the credentials from a secret in Hashicorp Vault. Instructions for doing this are included with the general instructions for enabling Vault integration.

Verify

Verify basic LDAP configuration settings

  • run the hubctl verify ldap

As a final check on the basic LDAP configuration settings, run the following command:

hubctl verify ldap

If verification is successful, the output will look something like the following:

INF Verifying LDAP server connection
INF LDAP connection successfully made and bind performed
INF Listing users returned 500 results
INF Listing groups returned 100 results
INF OK

If there are any errors, revisit the steps above to diagnose the problem.