LDAP Configuration

> Administration > Account Management > LDAP Configuration

If the enterprise has an LDAP server, the platform can be configured to automatically authenticate users against the LDAP Server when they log in.

How LDAP Works

Platform Behavior, User Experience and Administration

When a user logs in, the platform carries out the following sequence of activities:

• If their User record was created in the platform, they log in with those settings.
• If the user is not known to the platform, the LDAP directory is searched for a matching entry.

• If none is found, access is denied.
• If a matching entry exists, a new LDAP-enabled User record is created.

• Thereafter, when the user logs in, their password is validated against the LDAP directory.
• At the same time, any changes made to the user's LDAP settings are synchronized with the platform.
• During the LDAP user creation process in AgileApps platform, the following information is synchronized to the platform: first name, last name, email and username. This set is limited for security purposes.

As far as the user is concerned, therefore, they simply log in to the platform using the same credentials they use everywhere else.

And as far as admins are concerned, user information is maintained in one place--the LDAP server. Any changes made there are automatically seen by the platform.

Effect on User Profiles

When a user has an entry in an LDAP directory, most of their profile information is maintained in the LDAP server. The platform reads that information from the server. It can no longer be modified in the platform. The exception is profile information that is specific to the platform.

In particular:

• In the initial dialog a user sees when they log in, the Reset Password option is disabled.
• In the user's Personal Settings page, only the user's Team affiliation and default Application can be modified. Other settings can be viewed, but not changed.
• In the admin's Access Management > Users page:

• The option to Reset Password is disabled for LDAP users.
• The user's Team affiliation and default Application can be modified. Other settings can be viewed, but not changed.

LDAP Address Expressions

In its simplest form, LDAP can be thought of as a hierarchy of directories, each of which contains entries for users and other entities. But instead of using a URL to address those directories, you use a combination of syntax elements.

For example, consider the URL http://yourCompany.com/united_states/california/users/yourLDAPdata.
That path is specified in LDAP elements using the elements below:

• DC (Domain Controller) Used to specify the LDAP domain.

For example: DC=yourCompany, DC=com, which corresponds to yourCompany.com in the URL.

• OU (Organizational Unit) A group that can contain other groups. (Effectively, an "intermediate" group.)

For example: OU=california, OU=united_states, which corresponds to the URL path /united_states/california.

• CN (Common Name) A group that can contain individual entries, but which cannot contain subgroups.

For example: CN=users, which corresponds to the final directory in the URL.

Within that directory, the entry yourLDAPdata can be found.

Secure LDAP Server

A secure LDAP server is now supported with the protocol LDAPs, and with the port number 636.

Points to note:

• To connect to the LDAPs, it is recommended to upload valid certificate.
• Connection to LDAP server will fail if SSL connection is enabled and an invalid certificate is provided.
• Proper port should be used for SSL (ldaps://) and without SSL (ldap://) connection, else the LDAP server will not be reachable and AgileApps will deny the access.
• The SSL connection is disabled by default in the LDAP configuration screen and no modification is needed in existing configuration if you want to continue working with the plain LDAP (~without SSL).

Considerations and Limitations

• Active Directory is currently supported as server type.
• A single LDAP server is supported, for now.
• The search for a matching user does not yet span multiple groups, so a CN entry must be included either in the specification of the search directory, in the user or group directory designation, or in one of their filters. The search path cannot terminate at an Organizational Unit (OU) directory, as that would require searching the multiple subdirectories it contains.
• The user's Team cannot currently be configured using LDAP attributes. The default team is always used for a new user.
  (The team setting can be changed in the platform after the user logs in.)
• Similarly, to give a user access to multiple applications, or to change the user's initial application modify the Application Access settings after the user has logged in to the platform.

Working with LDAP

Configuring LDAP

1. Examine the configuration settings below to see which individual-user attributes can be populated from LDAP.
2. If desired, create attributes for those settings in your LDAP server.

   (If all users will have the same settings, this step is not necessary. They'll use the default settings you configure below.)

3. Go to > Administration > Account Management > LDAP Configuration
4. Fill in the configuration settings
5. Click [Save]

Configuration Settings

• Server Type - The type of LDAP server. Active Directory is the default.
• Server URL - The server domain and optional port. Port number 389 is the default port, used by the LDAP server.

For example: our.LDAPserver:998

For Secure LDAP server, the default Port number 636 is used.

---

• Login DN - The Distinguished Name of a user that has admin privileges.
• Password - The admin user's password.

---

• Starting Search Directory

A comma-separated list of DC and OU expressions that leads to the start of the search path.

Optionally, include a CN directive as well, to completely specify the directory to be searched.

---

• User DN - Optional. An LDAP expression that designates a path to an LDAP user directory, starting from the initial directory.
• User DN Filter - Optional. An expression that limits the LDAP entries that will be examined.

For example, use a setting like this one to exclude disabled users: !(userAccountControl=514)

Note: The (objectCategory=person) and (objectClass=user) parameters do not need to be specified. They are included automatically.

---

• Group DN - Optional. An LDAP expression that designates a path to an LDAP "group" (distribution list) directory, starting from the initial directory.
• Group DN Filter - Optional. An expression that limits the LDAP entries that will be examined.

For example, use a setting like this to exclude entries that include the word "test": !(mail=*test*)

Note: The (objectCategory=group) parameter does not need to be specified. It is included automatically.

---

• Read Timeout - Optional. This field contains a timeout duration in milliseconds.

It is a time to reconnect to the server when the server is busy, or the network is slow. When the time mentioned exceeds, an error will appear.

---

• Enable SSL - To have a secure LDAP server, this checkbox is enabled. Two additional fields appear on checking this field.

• Paste SSL Certificate - Paste the valid SSL certificate to access the secure LDAP server. Alternatively,
• Upload SSL Certificate - Upload a valid SSL certificate through a file to access the secure LDAP server in the section SSL Certificate. (with extension like - pem, cert etc.)

When field Enable SSL is disabled, no certificate is needed. You will be able to connect to the unsecure LDAP server.

---

---

• Default Team - A new user's default Team.

The team assignment can be changed in the platform after the user logs in.

The user can change it in their Personal Settings. An admin can do so in the Users page.

---

• Default Access Profile - A new user's default Access Profile.

The user's access profile is fully determined by the configuration.

• LDAP Attribute for Access Profile - The name of the LDAP attribute that designates the user's access profile.

The attribute must contain an access profile's record ID.

To get a record ID:

a. Go to > Access Management > Access Profiles

b. Modify the view to display Record IDs, and copy the ones you need.

---

• Default Application - The initial Application the user sees when they log in.

That setting can be changed in the platform after the user logs in.

The user can change it in their Personal Settings. An admin can do so in the Users page.

To grant access to additional applications:

a. When the user logs in, a User record is created for them in the platform.

b. You can then use the Application Access page to specify the applications the user can access.

• LDAP Attribute for Application - The name of the LDAP attribute that designates the user's application.

The attribute must contain the application's record ID.

To get a record ID:

a. Go to > Access Management > Application Access

b. Modify the view to display Record IDs, and copy the ones you need.

---

• Default Role - The new user's Role in the application.

That setting can be changed in the platform after the user logs in.

The user can change it in their Personal Settings. An admin can do so in the Users page.

• LDAP Attribute for Role - The name of the LDAP attribute that designates the user's role in the application.

The attribute must contain the role's record ID.

To get a record ID:

a. Open the application, if it is not already running.

b. Go to > Customization > Application Roles

c. Modify the view to display Record IDs, and copy the ones you need.

Synchronisation of the User state with the Platform

When the user is no longer active in the LDAP server or the user is removed, then this API is used to deactivate those users in AgileApps.

This is achieved by calling the JAVA API in Schedule rules or Macros in AgileApps.

To do this, you need to create a custom class similar to the below code snippet.

package com.platform.mynamespace.example;

import com.platform.api.*;

public class LDAPSyncHandler {
	public void syncLDAPUser(Parameters p) throws Exception {
       try {
         Logger.info("Invoking LDAP user sync", "LDAP User Sync");
         Result r = Functions.syncUsersStateWithLDAP(p);
         if (r.getCode() < 0) {
            Logger.error("Sync failed\n" + r.getMessage(), "LDAP User Sync Error");      
         }else{
          	Logger.info("Sync successful\n" + r.getMessage(), "LDAP User Sync Success!");  
         }
       } catch (Exception e) {
          Logger.error("Sync failed\n" + e.getMessage(), "LDAP User Sync Error");      
       }
    }
}

Note: You need to have the manage user permission enabled in your access profile, in order to use this API. You also need to have LDAP configuration enabled for this tenant. SSO must be disabled for this tenant. For any errors or success messages look into the Debug Log. [ > Customization > Developer Resources > Debug Log]