Use LDAP to Authenticate Access to LogicHub

Authentication for LogicHub access is handled through user accounts that you set up on the Settings > Users page.

This topic provides guidelines on configuring access to LogicHub by way of your corporate LDAP server.

It’s assumed that you already have a working LDAP server in your environment and that the machine that hosts your LogicHub instance has networking connectivity to your LDAP server.

After setting up the LDAP connection as described in this topic, you can select LDAP as an option when creating a new user account.

Task Overview

Perform all of these tasks on the machine that hosts your LogicHub instance.

  1. Modify the dynamic.conf file for your ‘Services’ Docker container.
    (optional) Set up a custom certificate to bypass the SSL exception when users log in.
  2. For administrator access to your LDAP server, obtain the correct DN to bind to the LDAP server.
  3. Obtain the correct DN for user authentication requests to the LDAP server.
  4. Construct the principal query for the user using the DN.
  5. Verify that the user access works.

Modify the dynamic.conf File for your ‘Services’ Docker Container

The dynamic.conf file is located in /opt/docker/data/service/conf/dynamic.conf. The file already has some content. To specify the LDAP configuration, add additional lines similar to the following. The specific lines for your instance depend on your environment. Refer to the following table for parameter descriptions.

lhub.ldap.providerUrl = "ldaps://ldap.dev.logichub.com:636" 
lhub.ldap.principalQuery = "uid=%CN%,ou=People,dc=logichub,dc=com"
lhub.ldap.trustAllCerts = true (optional if the client has the correct cert) 
lhub.ldap.groupSyncMode = "off"  # Valid sync mode options = "off", "on", "dryrun"
lhub.ldap.adminGroupQueryBaseDN = "ou=Admins,dc=logichub,dc=local"
lhub.ldap.adminGroupQueryBindDN = "cn=ldapadm,dc=logichub,dc=local"
lhub.ldap.adminGroupQueryBindPassword = "*****PASSWORD*****"
lhub.ldap.userGroupQueryBaseDN = "ou=Users,dc=logichub,dc=local"
lhub.ldap.userGroupQueryBindDN = "cn=ldapadm,dc=logichub,dc=local"
lhub.ldap.userGroupQueryBindPassword = "*****PASSWORD*****"

Parameter

Description

lhub.ldap.providerUrl

Hostname and port of the LDAP server. Both ldap and ldaps are supported.

lhub.ldap.principalQuery

Query made to the LDAP server for authentication of a specific user. %CN% is a variable that represents the login name of the user who is being authenticated.

lhub.ldap.trustAllCerts

(optional) If you include this entry and set the value to true, the SSL security exception is ignored even without additional certificate setup.

lhub.ldap.truststore.location

(optional) For custom certificate, specifies the location where the certificate is stored.

lhub.ldap.groupSyncMode

Specify whether to synchronize LDAP group membership before authenticating. Values: off, on, or dryrun

lhub.ldap.adminGroupQueryBaseDN

Base distinguished name. Organizational location from where the search for the admin LDAP user will take place.

lhub.ldap.adminGroupQueryBindDN

Bind distinguished name. Admin user and location of the user in the LDAP tree structure.

lhub.ldap.adminGroupQueryBindPassword

Password for the admin LDAPuser.

lhub.ldap.userGroupQueryBaseDN

The user settings (this entry and the two following entries) can be used instead of the three admin entries above them. These entries are for a non-admin user to bind to an LDAP server and make queries.

Base distinguished name. Organizational location from where the search for the LDAP user who will access LogicHub takes place.

lhub.ldap.userGroupQueryBindDN

Bind distinguished name. User and location in the LDAP tree structure.

lhub.ldap.userGroupQueryBindPassword

Password for the LDAP user to connect/bind to the LDAP server.

(Optional) Set Up a Custom Certificate to Bypass the SSL Exception When Users Log In

If your LDAP server doesn’t have a certificate that is signed by a real certificate authority (CA), update the trust store to trust the certificate of your LDAP server.

In this example, the certificate of an LDAP test server, ldap.dev.example.com, is added to the LogicHub trust store.

  1. Copy the logichubldapcert.pem file from the LDAP server to the client server.
scp ldapcertificate.pem <username>@test.dev.example.com:```

2. Copy the .pem file into the Docker Service container
```docker cp ldapcertificate.pem service:/opt/docker```

3. Run the following command from /opt/logichub/data/service/.

```keytool -import -alias ldap -file ldapcertificate.pem -keystore logichub_dev```

### Verify the Certificate


[block:callout]
{
  "type": "info",
  "title": "Getting the ldapsearch tool",
  "body": "yum install openldap-clients"
}
[/block]

To verify that the certificate is good, use the [ldapsearch command](https://linux.die.net/man/1/ldapsearch). The following is an example that you can adapt for your environment. 

```env LDAPTLS_CACERT=path-to-ldap-cert.pem ldapsearch -H ldaps://localhost:636 -D cn=ldapadmin,dc=logichub,dc=com -b "ou=Users,dc=example,dc=com" -s sub "objectclass=*"```

If there are issues with this command, try adding the flags ```-ZZ`` and ```-d 1``` to get more details.

This process requires the entire trust chain. If you don’t have access to the entire trust chain, you need to establish the trust in some other way (such as the signer's certificate and intermediate certificates to the right location).

If you only have the server certificate you can obtain the whole trust chain by using this command:
```openssl s_client -showcerts -connect your_ldap.your_company.com:1636  >> cert_output.txt```

You can then edit the cert_output.txt file to remove everything other than the blocks bounded by:

```BEGIN CERTIFICATE``` 
```END CERTIFICATE```
 
The remaining content can be used as the .pem file for certificates.

You can also bypass certificate verification in ldapsearch by using this command:

```env LDAPTLS_REQCERT=never ldapsearch -H ldaps://localhost:636 -D cn=ldapadmin,dc=logichub,dc=com -b "ou=Users,dc=logichub,dc=com" -s sub "objectclass=*" ```

### For administrator access to your LDAP server, obtain the correct DN to bind to the LDAP server.

On Windows systems, use the following process to obtain the correct base DN for administrator access to the LDAP server.

1. Select **My Computer** > **Network**.
2. Search Active Directory (button near the top of the window)
3. Select **View** >  **Choose Columns.**
4. Highlight **Distinguished Name** and click **Add**.
5. Search for a known user.  
6. Expand ‘Distinguished Name’ to reveal the full Base DN.

On Linux systems, use the ```ldapsearch``` command to obtain the base BN. 

### Obtain the correct DN for user authentication requests to the LDAP server

Follow the same process as in the previous section to obtain the correct DN for user access.  

### Construct the Principal Query for the User Using the DN

The principal query for user access to the LDAP server is of this form:
```lhub.ldap.principalQuery = "uid=%CN%,ou=People,dc=logichub,dc=com"```

### Verify that the User Access Works

After using the principal query, verify that a known LDAP user can log in to LogicHub with LDAP credentials.

 

Did this page help you?