UID - Manage an LDAP Directory Integration

This article describes how UID administrators can enable and configure Directory Integration on UID to use Lightweight Directory Access Protocol (LDAP) for user login and to import users currently active in a directory. 

• Install and configure LDAP on UID
• Configure JumpCloud in UID
• Configure Google LDAP in UID
• Import your directory users to UID
  • Create user importing rules
  • Manually import users
  • Schedule an importation task
• Troubleshooting

Install and configure LDAP on UID

To set up the Directory Integration on UID:

1. Go to your UniFi OS Console dashboard and launch the UID agent application. Click the Set Up button to set up the Directory Integration.
   

   

   If you do not see the option to set up the Directory Integration, it means it is not included in your plan and you must request the feature.

   Need help requesting the Directory Integration feature?

   1. Navigate to the UID Manager Portal > Settings > Plan and click Apply for Plan Quota under the Workspace Plan header. 

   2. Select LDAP Integration as an additional feature and click Submit Application.

   3. Once your submission is accepted and your plan request granted, you must update your UID Agent token:

       a. Go to Workspace Settings > UniFi OS Consoles > UID Agent Token to create a new token.

       b. Go to UniFi OS Console > UID Agent to update the UID Agent token.

2. Select the LDAP option and fill in the fields with your LDAP server’s information.
   

   

   To configure JumpCloud's LDAP server, please refer to their documentation here.
3. Click Done and navigate to the UID Manager Portal > Users > Directory Integration to complete the integration. Select your directory.
   

   

4. Map the values and test the configuration on the Configure Integrations on UniFi OS step. When successful, click Save. 
   
   Need help understanding any of the Configure Integrations on UniFi OS fields?

   • LDAP Version: Select your vendor. Vendor-specific configuration templates are provided and its configuration settings are pre-populated. If your LDAP vendor is not on the list, complete the configuration fields manually. Because each LDAP environment is unique, please confirm the default values using an LDAP browser like Apache Directory Studio. Note that not all configuration settings must have values.
   • Unique Identifier Attribute: Specifies the unique immutable attribute of all LDAP objects that will be imported (users and groups). Only objects possessing this attribute can be imported into your UID org. UID populates this field automatically based on your chosen LDAP version. You can change the auto-populated value during initial setup. Note: If your LDAP server implements RFC, make sure to enter entryuuid in this field. For AD LDS, use objectguid.
   • User Search Base: The DN of the container for user searches (that is, root of the user subtree). This is the base DN of the container that holds all users that will be imported into your UID organization.
   • User Object Class: The objectClass of a user that UID uses in its query when importing users. For example, inetorgperson, posixaccount, posixuser.
   • User Object Filter: By default, UID auto-populates this field with the objectClass (objectClass=<entered objectClass name>). This must be a valid LDAP filter.
   • Group Search Base: The DN of the container for group searches (that is, root of the group subtree) that holds all groups that will be imported into your UID organization.
   • Group Object Class: The objectClass of a group that UID uses in its query when importing groups. For example, groupofnames, groupofuniquenames, posixgroup.
   • Group Object Filter: By default, UID auto-populates this field with the objectClass of the group (objectClass=<entered objectClass name>).
   • Member Attribute: The attribute containing all the member DNs.
   • User Attribute (Optional): UID uses the member attribute on the group object to determine the user group memberships at runtime. Unless your group object and group filter is explicitly posixGroup and (objectclass=posixGroup), leave the user attribute field empty. In case where you are using posixGroup, we recommend that you configure the member attribute value to memberuid and the user attribute value to UID.
   • Example Email: Verify the settings by entering the email here to confirm that the required user attributes and group memberships can be properly obtained from LDAP.

   If you select Google LDAP as your LDAP vendor, you'll need to also fill out the additional fields below:

   • Name Attribute: Define the user name.
   • SN Attribute: Define the last name of the user.
   • Email Attribute: Define the user's email address.
   • Update Time (Optional): Update the time of the user or group.

    

   
   

   

   
   You can come back to the LDAP’s Integration tab at any time to edit the mapping between UID and your directory.
5. Go to the Settings tab to configure your preferences for the user-importing experience.
   

   

   Need help understanding the LDAP Integration Settings fields?

   • Schedule import: set up periodical directory user scans to import new users or new data for existing users.
   • Allow partial match on first and last name: When the imported user email does not match the existing UID user’s email, but their first name and last name match the existing UID user’s first name and last name, partial matching is allowed.
   • Auto-confirm exact matched users: The user will be imported to UID automatically if the emails are an exact match. 
   • Auto-confirm new users: The new user will be imported to UID automatically, without needing to await confirmation.
   • Auto-activate new users: After the Auto-confirm new user is enabled, this option will be displayed. Enable it to activate new users as soon as they’ve been imported without needing to be manually activated. Go to Settings to configure your preferences for the user-importing experience.

   Continue to the next section to learn how to import users quickly and easily.

Configure JumpCloud in UID

Before configuring UID to use JumpCloud’s LDAP-as-a-service, please refer here. You must use UID Agent version 0.45.1 or above to configure JumpCloud LDAP.

Enter in the information below:

• LDAP Server: ldap.jumpcloud.com:389
• Root DN: ou=Users,o=YOUR_ORG_ID,dc=jumpcloud,dc=com
• Bind DN: uid=LDAP_BIND_USER,ou=Users,o=YOUR_ORG_ID,dc=jumpcloud,dc=com
• Bind Password: LDAP_BIND_USER_PASSWORD

Configure Google LDAP in UID

To create a client using Google's secure LDAP service, follow the instructions here. You must use UID Agent version 0.45.1 or above to configure Google LDAP.

Note: You must have a Google Workspace account that can log into admin.google.com (not a personal account) and be using the Business Plus, Enterprise, Education Fundamentals, Standard, Teaching and Learning Upgrade, or Plus editions.

To test your connection with UID Agent, enter the fields below:

• AD Server is the local IP Address
• Port is the local proxy port number configured above
• Download the certificate and extract the .zip file to two separate files (.crt and .key), then upload them to the Client Certificate and Key Certificate sections in the UID AD/LDAP Integration form
• Generate new credentials for Username and Password in Google Admin's LDAP page

Import your directory users to UID

You can import users more efficiently by creating rules that will customize the task and schedule importing runs to automatically scan for users that need to be imported at periodic intervals. If you wish to import your users right away without configuring rules, skip to the manual importation instructions.

Create user importing rules

1. Go to UID > Users > Directory Integration and select your configured directory.
2. Navigate to Rules > Add Rule.
   

   

3. Name your rule, and determine to which UID group users will be added to when they meet the rule’s conditions. If there are multiple conditions, the user will have to meet all of them in order to be imported.
   

   Note: Conditions stated in the rule must be exact matches. Verify in your LDAP the exact names of values you are using as conditions.

   

Manually import users

1. Go to UID Manager Portal > Users > Directory Integration and select your configured directory. If needed, adjust your configuration choices in the Settings and Integration sections.
2. Go to Import and click Import Now.
3. Make your import method selection and click Import.
   

   

4. The resulting list of users will display the match level between the directory user and its UID counterpart. An exact match means the emails matched perfectly. A partial match means the email did not match, but both first and last name matched perfectly.
   

   

5. Set the actions for each user, select them by ticking the checkbox and click Confirm Assignments.
   

   Note: The action behavior will vary depending on the selections made in Settings.

   • Create New User: If the Auto-activate users after confirmation option is enabled in Settings, the user’s status will be pending while the system sends them an activation email. If it is not enabled, the user's status will remain in Staged and no email will be sent until an administrator manually triggers it.
   • Merge: If either Partial Match or Exact Match are enabled in Settings, the merge action is supported. After successfully importing, the original directory user data will overwrite the existing UID user data.
   • Specify: Select this option to manually select an existing UID user to be this imported user’s match.
   • Ignore: When there are users in the Import list that do not need to be imported into UID, select the user and Ignore action to skip importing the user.

Schedule an importation task

You can set the Import Schedule and Schedule import mode to import users into the UID system regularly according to the configuration. Select Never for Schedule Import to prevent automatically importing users.

To schedule an importation task go to the directory’s Settings > Schedule import mode and select the importing method from the drop-down list. These scheduled tasks will run according to the rules you configured (if any).

Troubleshooting LDAP issues

Failed to import users into UID.

1. Confirm that the directory type is LDAP within UID Manager Portal > Users > Directory Integration. If you mistakenly selected Active Directory and filled it with your LDAP server information, you will be unable to obtain the users information.
2. If there are new organizations added in the LDAP server, please go to the Import page and click Import Now to update the list.

How do I remove a configured directory from UID?

1. Deactivate it first by going to UID Manager Portal > Users > Directory Integration.
2. Select your directory and change its status to Deactivated using the dropdown underneath its name.
3. Go back to the Directory Integration page, hover over the configured directory’s three-dot menu and select Delete.

I’m seeing an “Test Fails” error.

To troubleshoot the LDAP configuration and network connection:

1. Use this command to test the connection: telnet istemp.net 389
   • If it results in a “Connected to xxxx” message, it means the connection works normally. 
   • If it keeps attempting to connect, it means there is a connectivity problem.
2. If you are facing connectivity problems, check that the correct ports are open. The standard LDAP protocol is by default on TCP and UDP port 389, or on port 636 for LDAPs (LDAP over TLS/SSL).
3. If the issue persists, check your network configuration settings. If there is a port forwarding configured, verify that it is working properly.
4. Use the tool http://www.ldapadmin.org/ to try and connect.