LDAP Synchronization

Overview

Over time, user accounts need to be created, updated, and deactivated. Customers who have an existing user directory can use the LDAP Tools plug-in to automatically mirror these changes to Appian without requiring users to work manually through the web interface or with CSV files.

Periodically synchronizing users with a directory service ensures that only authorized users have accounts in Appian and that their user profiles are consistent with the system of record. Furthermore, synchronizing users between Appian and the directory service provides Shared Sign On features when using Appian native authentication. Customers can elect to combine LDAP sync with external authentication mechanisms such as SAML or Kerberos to offer true Single Sign On capability.

User Profile Synchronization

There are several ways LDAP can be used to create accounts in Appian. The LDAP Tools plug-in smart service node can be used to update Appian user profiles in bulk from returned LDAP queries. The data that can be synchronized includes all the default user profile fields (e.g., first name, last name, address, phone, supervisor, title, etc.) as well several custom fields. These details can then be used to create and update accounts and modify group membership.

Another common method to generate user accounts is to have them updated and populated with details from LDAP when a user logs in. Although this approach is useful for customers who don't have an existing Appian user directory or who don't want to synchronize users in bulk using LDAP sync, users are not visible in the system and cannot be added to groups (e.g., for task assignment) prior to their initial logon. Furthermore, this create-on-login paradigm does not support user deactivation. This approach requires the use of a custom Java extension to the external system and must be maintained independent of Appian. This is outside the scope of the LDAP tools plug-in.

It is recommended to use the first approach in a nightly batch process. This handles the issues discussed above and ensures that the authorized user list is up to date. Please refer to the LDAP Sync application included with the plug-in for more information.

Important Considerations

All operations by the plug-in are driven by LDAP queries on object classes, attributes, and groups. As such, if you are not familiar with LDAP terminology, please proceed with caution.

While the process can facilitate the creation of users in Appian, users accounts can never be deleted, only deactivated. Therefore, it is important to ensure that only the users you expect to be imported is actually imported. In a pre-production environment, test the queries using the Configure LDAP Synchronization action included in the LDAP Sync application.

Prerequisites

Before attempting to use the LDAP Tools plug-in, identify the following information for your environment:

LDAP Sync Application

The LDAP Tools shared component includes an application that, when configured, synchronizes the directory service users to Appian. The application will also manage Appian group membership.Note: The application only synchronizes users and their group association within Appian, it does not create groups to mimic the directory service structure.

The process automatically:

• Creates Appian users that do not exist
• Deactivates Appian users that have been removed from the directory service
• Reactivates previously deactivated Appian users
• Updates Appian users with any changes made to their respective directory service entries

This process can be run nightly ensuring all authorized users have accounts. If more frequent updates are required, especially when dealing with large group sizes, they can be scheduled during off peak hours to ensure the update process does not overlap with high volume usage.

Use Cases

The following examples demonstrate the cases the nightly synchronization handles.

Case 1 - A new entry, John Smith, is added to the directory service. This entry is captured by at least one of the LDAP queries run during the nightly LDAP synchronization process and a new Appian user with the same details is created.

Case 2 - The user added in the previous case is updated. Additionally, Jane Doe, is removed from the directory service. Both of these changes are captured by the nightly synchronization. In Appian, the first name john.smith user account is updated to Jonathan. The jane.doe account is not returned by any of the LDAP queries and is then deactivated in Appian.

Case 3 - An existing directory service entry is modified so that a user is removed from a directory service group. This results in the none of the LDAP queries returning this user. The user is deactivated and removed from the associated Appian group.

LDAP Sync Tutorial

1. Setup up a directory service. Please skip to Step 2 if you already have a directory service configured. For the purposes of this tutorial, we recommend using openDJ. During the "Directory Data" step of the installation define your Base DN and automatically generate sample data.
   • Define the Base DN as dc=appian, dc=com and create 100 users.
2. Browse the directory with a third-party client such as JXplorer and confirm that the entries to be imported have the minimum basic user criteria. Also take note of the expected number of created Appian users as well as any distinguishing attributes that can be used to generate a targeted search filter.
3. Deploy the LDAP Tools plug-in on your Appian instance.
4. Import the LDAP Sync application into your environment.
5. Set up a Secure Credential Store to include the authentication credentials for the directory service:
   • Navigate to the Administration Console.
   • Navigate to Third-Party Credentials.
   • Click Create.
   • Enter a Name, this is the secured credential store (SCS) key, e.g., ldap.acme.
   • Click +Add field to create a new field named username, this is the relative distinguished name (RDN) for the ldap administrator, e.g. cn=admin.
   • Click +Add field to create a new field named password, this is the password for the administrator user, e.g., secret.
   • Select LDAP Tools in Plug-ins field.
   • Click Save.
6. In Tempo, click Actions, and then click Configure LDAP Synchronization.
7. Fill out the following required fields:

   Field	Description	Example
   Protocol	Protocol used to connect to ldap server	ldap or ldaps
   Server	Host running the ldap server	ldap.server.com
   Port	Port used to connect to the ldap server	389 or 636
   Secure Credential Store Key	Name of third-party credential contains ldap admin details	ldap.acme
   Connection Type	Set to ssl if using a non-standard key store	clear or ssl
   All LDAP Users Group	If a user is a member of this group, but not returned by any of the LDAP group filters, the user is deactivated	All Users
   User Attribute Mapping	Mapping of ldap attributes to Appian user profile fields, the following are required: Username, First Name, Last Name, Email	uid, givenName, sn, mail

8. Create at least one group filter which is used to synchronize the LDAP query results with membership to an Appian group:
   • In the Group Membership section, click +Add Item to add a new Group Filter.
   • Enter a Display Name for the filter, this is used to name the process instances which synchronize this group.
   • Enter the Base DN for the query, if left null the entire directory is searched.
   • Enter the LDAP Filter used to query the desired subset of users.
   • Enter the Appian Group whose members should be determined by this filter.
9. Check the box next to the newly created row and click Test Filter.
   • This action returns either the results for the filter or an error and a suggested remedy.
   • The fields displayed in the results table correspond the mapped attributes in the User Attribute Mapping section.
10. Once all filters have been created and tested click Submit to save the settings.
11. To turn on nightly sync do the following:
    • Open the Configure LDAP Synchronization action.
    • Check the Enable LDAP Sync checkbox.
    • Enter the time when the sychronization process should runNote: this requires republishing of the LDAP - Scheduled Job process model in order to integrate the new start time.
    • Verify process runs at appointed time and daily thereafter.

Troubleshooting

Below are some of the most common errors encountered when using the plug-in. Confirm with the plug-in’s documentation and your directory services’ manual for more specific information.

Error Code 12

An error code 12 response is received when using the ldapsearch function in Appian, despite confirming that the directory service is browsable and searchable using third-party tools such as JXplorer:

LDAP: error code 12 - Unsupport critical control 2.16.840.1.113730.3.4.9

LDAP: error code 12 - LDAP_UNAVAILABLE_CRITICAL_EXTENSION

The plug-in presumes that your directory service supports virtual list view request control (VLV). If this is not the case, update the Virtual List View Control Supported field using the Configure LDAP Synchronization action.

Error Code 49

An error code 49 response is received when using the ldapsearch function in Appian:

LDAP: error code 49 - Invalid Credentials

Check the Secure Credential Store and confirm that your logon credentials are correct. Passwords are case sensitive. The username must be entered with its full RDN (for example, cn=admin, not admin).

Unable to Bind to LDAP Server

An Unable to bind to LDAP server error is usually returned when the directory service is down. Confirm that the server is operational, has an IP Address, and is not blocked by any firewall before trying again.