Using LDAP

Owned by Jonathan Schmale
Last updated: Sept 27, 2023
8 min read

You can enable individual users to login using an LDAP-compatible directory (Example: Microsoft Active Directory) username and password instead of having a separate password in Flow while at the same time allowing other users to login using Flow defined credentials.

Key Ideas

  1. You still need to create an account in Flow for each user to be able to assign privileges in Flow.

    1. The username on the account in Flow must match their username in the LDAP directory.

    2. The user accounts can be created manually or importing data from a CSV formatted file. See the Import Users page for more information.

  2. When they login Flow will check the password against the LDAP-compatible directory instead of the Chameleon database.

  3. Use of LDAP must be enabled on each user account it will be used with as well as turning on the main "Allow LDAP Login" on the LDAP config page.

  4. If you have existing users with passwords that are already in use - you can still switch their account to use LDAP. Activating LDAP support will not remove those existing passwords.

Create a User with LDAP

When you want a user to connect using their LDAP login you need to define their account in Flow making sure you set a few key fields.

  • User Name must match the LDAP user name.

  • Login Method must be set to LDAP.

  • LDAP Group may be assigned (optional).

  • The rest of the fields are assigned the same way as they would for any user.

 

LDAP Configuration

You access the LDAP settings using 2 alternate methods.

Login as a System Administrator

After logging in open the System Tools - Configuration module. This module can be accessed by a logged in System Administrator and will appear near the bottom of the main dashboard page.

Alternate - Login using the Config User

This could allow you to access the LDAP settings if needed to without using an LDAP based user login first.

You login to the password protected configuration page directly using a Config url for your installation in the format such as https://chameleon.blcloud.net/config

You will be prompted to enter your Config user password that grants you access to the Configuration module.

Connection Testing

You can test your connection settings before you enable them. To do so - fill in the all the configuration settings. You don't even have to save the settings - the test buttons use the values entered into the form - not the saved values.

Test a Basic Server Connection - Optional

  1. Fill in all the necessary configuration settings.

  2. Press the Test Connection button.

  3. You will get a message box telling you if the connection succeeded or not.

NOTE: this will not work if your server doesn't support anonymous binds (unauthenticated access). It may work when used on a server in your domain but then not work from a server outside its domain. But even if this doesn’t work - the user logins can still work because they use a user id and password.

Test the Search User

  1. Fill in all the necessary configuration settings.

  2. Press the Test Search User button.

  3. You will get a message box telling you if the connection succeeded or not.

NOTE: this may work even if the basic server test connect does not because it is using the search user id and password to authenticate.

Test a User Login

This test does not require a Flow user to be created yet.

  1. Fill in all the necessary configuration settings.

  2. Enter the user id and password in their respective boxes

  3. Press the Test User Login button

  4. You will get a message box telling you if the connection succeeded or not.

If this works then you are ready to enable using LDAP authentication with your user accounts. To do so you will still need to create user accounts in Flow. This can be done manually or with a User Import.

Setting Details

The individual settings required are also documented inline on the configuration page.

In order to connect you'll need to be able to specify:

Setting

Comments

Setting

Comments

Host Name

 

The host name of your directory server. Examples:

  • activedir.example.com

  • ldap.example.com

Port

The port on which your directory server is listening. Examples:

  • 389

  • 10389

  • 636 (for secure/encrypted connections - LDAPS)

Use SSL

Enable when using LDAPS via port 636.

Use this option to turn on alternate SSL option settings in the connection. Be sure to use the matching port. The default port for LDAP with SSL is 636.

Timeout

The number of seconds to wait for a result from an LDAP request before timing out.

Search User DN and Password

The distinguishedName (DN) of the user to login with to perform user searches. This user needs to only be granted view/search privileges. It does not update the directory.

Example: cn=read-only-admin,dc=example,dc=com

It may also need to take the format Domain\UserName

These fields aren't always required. They are not used if you have a situation where the user DN can be directly determined via a concatenation of User Attribute, User RDN, Base DN. See more notes on this below this table of settings.

The saved password is not displayed.

Search Filter

The filter used when searching for users in the directory. Examples:

  • For LDAPv3: (objectClass=inetOrgPerson)

  • For AD: (objectCategory=person)(objectClass=user)(!sAMAccountType=805306370)

Base DN

The root distinguished name (DN) to use when running queries against the directory server. Examples:

  • o=example,c=com

  • cn=users,dc=ad,dc=example,dc=com

  • For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc=local.

    • You will need to replace the domain1 and local for your specific configuration.

    • Microsoft Server provides a tool called ldp.exe which is useful for viewing and configuring the LDAP structure of your server.

User Attribute

The attribute of an LDAP user object that specifies the login name of the user. Examples:

  • cn

  • uid

  • sAMAccountName

Additional User RDN

(multiple)

This value is used in addition to the base DN when searching and loading users. If no value is supplied, the search will use the base DN. Example:

  • ou=Groups

You can define multiple User DNs and assign each a friendly name that is selected when setting up the user in the user module.

NOTE: the User RDN values should not include the Base DN at the end. The application will automatically append the Base DN so providing it as part of the User RDN will make the final path incorrect. You may see an error in the Error Report:

System.DirectoryServices.DirectoryServicesCOMException (0x80072020): An operations error occurred.

Search User Notes

If using the cn user attribute as the login name then you may be able to use the LDAP authentication without the need for a search user. The application concatenates the user attribute and value to the additional user dn and the base dn to build the complete user distinguishedName (DN).

If using an alternate attribute that is not part of the defined user distinguishedName - then a search user is required to allow the app to search for the user by using the alternate attribute (eg. sAMAccountName) and then grab the user distinguishedName from the user record.

Either way: the application then passes the unique DN and password to the LDAP server to check if the combination is valid and if so they are allowed to login.

Connect and Setup Debugging

If you are not able to successfully connect with the search user or specific user logins then the following ideas may help you to troubleshoot the issue.

Key Settings to Check

  1. Are the correct host and port values being passed in?

  2. Is the search filter criteria correct?

  3. If it found a user did it successfully extract the full and correct user DN to then authenticate with?

LDAP Tracing

You can enable a preference key to enable additional logging. In the Preferences module search for "tracing". You will find an LDAP Tracing option. Set this option to True to enable it.

When the tracing option is enabled you can view the messages in an audit report. From the dashboard/home page look for the Reports item in the System Tools group. Once the Report module opens select the Login Audit Events option from the Report Type drop down list.

These events can then be cross referenced with the Error Report with any errors that occur during the process.

Check the Error Report

Errors that occur should be written to the standard Error Report that is viewable via the Reports module. You will find the reports module in the System Tools section on the dashboard.

Then inside the Reports module click on the Errors tab to open the Errors Report.

Possible Error Messages

System.DirectoryServices.DirectoryServicesCOMException (0x80072020): An operations error occurred.

If you see this following error - it may be because

  • You were testing a basic server connection but the server doesn’t allow anonymous binds. (That’s okay the user logins might still work.)

  • You were testing a user login and the User RDN has the Base DN included and it shouldn’t.

Example of a tracing audit log (in this example the User RDN had the Base DN appended. Once removed the User login test was successful. Look in line 4 and see where the OU has the repeated text at the end:
OU=MYTV,DC=ad,DC=example,DC=net,DC=example,DC=net

2022-01-28 5:32:48 AM SYS admin LDAP: IsUserValid: NO - failed finding ldap user via login search. 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: Error Message: An operations error occurred. 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: Search Filter: (&(objectCategory=person)(objectClass=user)(!sAMAccountType=805306370)(sAMAccountName=167777)) 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: Connection: LDAP://10.10.10.10:389/OU=Users,OU=MYTV,DC=ad,DC=example,DC=net,DC=example,DC=net Username: CN=MYTV BE Service Account,OU=Admins,OU=MYTV,DC=ad,DC=example,DC=net 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: Host: 10.10.10.10 Port: 389 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: 167777 RDN: OU=Users,OU=MYTV,DC=ad,DC=example,DC=net 2022-01-28 5:32:48 AM SYS admin LDAP: FIND USER DN: We need to find the users distinguishedName (DN) that we can use to verify the password. 2022-01-28 5:32:48 AM SYS admin LDAP: IsUserValid: Host: 10.10.10.10 Port: 389 2022-01-28 5:32:48 AM SYS admin LDAP: IsUserValid: Login: 167777 RDN: OU=Users,OU=MYTV,DC=ad,DC=example,DC=net 2022-01-28 5:32:48 AM SYS admin =========== LDAP TEST USER LOGIN ============ 2022-01-28 5:32:18 AM SYS admin LDAP: IsUserValid: YES 2022-01-28 5:32:18 AM SYS admin LDAP: IsUserValid: Attempt to connect to Host: 10.10.10.10 Port: 389 with the user DN and pwd 2022-01-28 5:32:18 AM SYS admin LDAP: IsUserValid: DN: CN=MYTV BE Service Account,OU=Admins,OU=MYTV,DC=ad,DC=example,DC=net 2022-01-28 5:32:18 AM SYS admin LDAP: IsUserValid: Check if this user and password is valid. 2022-01-28 5:32:17 AM SYS admin =========== LDAP TEST SEARCH USER ============ 2022-01-28 5:32:12 AM SYS admin LDAP: Test Connection: FAILED! Message: An operations error occurred. 2022-01-28 5:32:12 AM SYS admin LDAP: Test Connection: LDAP://10.10.10.10:389/DC=example,DC=net 2022-01-28 5:32:12 AM SYS admin LDAP: Test Connection: Host: 10.10.10.10 Port: 389 BaseDN: DC=example,DC=net 2022-01-28 5:32:12 AM SYS admin =========== LDAP TEST CONNECTION ============

The following is a sample error report entry from the example above.

Date

Source

Local Message

Error

Date

Source

Local Message

Error

2022-01-28 5:32:48 AM

System.DirectoryServices

LDAP user login - FindUser error.

System.DirectoryServices.DirectoryServicesCOMException (0x80072020): An operations error occurred. at System.DirectoryServices.DirectoryEntry.Bind(Boolean throwIfFail) at System.DirectoryServices.DirectoryEntry.Bind() at System.DirectoryServices.DirectoryEntry.get_AdsObject() at System.DirectoryServices.DirectorySearcher.FindAll(Boolean findMoreThanOne) at System.DirectoryServices.DirectorySearcher.FindOne() at Flow.Common.LdapHelper.FindUser(LdapServer server, String userAdditionalDn, String loginName)

LDAP Test App

See notes about this app: https://bannisterlake.atlassian.net/wiki/spaces/ST/pages/3070197768