Lightweight Directory Access Protocol (LDAP)

About LDAP

Lightweight Directory Access Protocol (LDAP) is used for querying and managing directories that run over TCP/IP. Microsoft Active Directory represents one implementation of LDAP. APM supports integration with Microsoft Active Directory to facilitate automatic login and synchronization of user information.

LDAP is not limited to contact information, or even information about people. LDAP is used to look up encryption certificates, pointers to printers and other services on a network, and to enable same sign-on, where one password for a user is shared between many services. LDAP is appropriate for any type of directory-like information, where fast look-ups and less-frequent updates are standard.

As a protocol, LDAP does not define how programs work on either the client or server side. It defines the "language" used for client programs to talk to servers (as well as servers to servers). On the client side, a client may be an email program, a printer browser, or an address book. The server may speak only LDAP, or have other methods of sending and receiving data; LDAP may just be an add-on method.

LDAP continues to be a popular standard for communicating record-based, directory-like data between programs.

About Domain Records

Domain records store identifying information about the Microsoft Active Directory domains that exist in your organization.

For LDAP integration to work properly:
  • At least one Domain record must exist to identify the Active Directory domain that contains user accounts that you want to synchronize with APM. You can create as many Domain records as needed to identify all the domains from which you want to retrieve user information.

The baseline APM product contains a Domain record that you can use as the basis for creating the one required Domain record.

  • If you have only one Microsoft Active Directory domain, you can simply modify the baseline Domain record.
  • If you have multiple Active Directory domains, you can modify the baseline Domain record and create new records to identify your additional domains. When you create a new Domain record, the default values will match those of the baseline Domain record to provide a guideline for specifying values in the new record.

About LDAP Field Mapping Records

LDAP Mapping records define how fields in Microsoft Active Directory user accounts correspond to fields in APM user records. The mappings that are defined in LDAP Mapping records are used to synchronize data between Microsoft Active Directory and APM. The LDAP Mapping records determine what information should be retrieved from Microsoft Active Directory and where it should be stored in APM.

Each LDAP Field Mapping record contains the following types of fields:
  • LDAP Field: Defines the source fields in Microsoft Active Directory.
  • Meridium Field: Defines the target fields for the corresponding Active Directory fields in APM.
When LDAP synchronization occurs, data is pulled from the source fields (values defined in the LDAP Field boxes) and used to populate the value in the corresponding target fields (defined by the Meridium Field boxes).
An LDAP Mapping record must exist for each Microsoft Active Directory field that you want to map to a APM field. APM provides a set of baseline LDAP Mapping records that map standard Microsoft Active Directory fields to fields in APM. If you want to change the mappings that are defined through the baseline records, you can modify the records as needed. However, we recommend that you retain the standard field mappings defined in the baseline LDAP Mapping records.
Important: If you want to map additional information to APM, you can create new field mapping records using only the reserved APM fields that are available for mapping with LDAP fields. You must not use any APM fields other than the reserved fields to create Field Mapping records.

About the LDAP Synchronization Process

When a scheduled or manual synchronization is run, LDAP will gather updated information from Microsoft Active Directory, import it into APM, and update the corresponding Security User records. When the synchronization process is run, APM Security User properties and status will be updated to reflect the last saved information in Microsoft Active Directory.

Note: To ensure that your APM system is in sync with the Microsoft Active Directory system, schedule the synchronization process to run on a frequent basis (every hour or more).

The synchronization process will import to APM only the changes (i.e., new users and updated information) that have been made in Microsoft Active Directory since the last synchronization ran, based on the Last Execution date in the job schedule item. Because only changes are imported to APM, the more often you run the synchronization process, the faster it will be (i.e., the fewer the changes, the faster the process). If you need to perform a full update in APM, you will need to delete and recreate the scheduled item to clear the Last Execution date. Performing a full synchronization will take longer than performing an update synchronization.

What Happens During Synchronization?

When a synchronization operation is performed:
  • The APM system will retrieve the information for the Microsoft Active Directory users associated with the Microsoft Active Directory domains that have been defined in APM. The corresponding Security User records will be updated. Fields in APM will be updated with the information in Microsoft Active Directory using LDAP Field Mapping records.
  • If the APM system finds a user in Microsoft Active Directory who does not have a corresponding Security User record in APM:
    • A Security User record will be created in the APM database.
    • The Security User record will be linked to the Domain record that identifies the Microsoft Active Directory domain in which the user exists.
    • The Security User will be associated with each APM Security Role whose name matches exactly the name of a Microsoft Active Directory Group to which that user belongs.
    • The Security User will be removed from each APM Security Role whose name does not match exactly the name of a Microsoft Active Directory Group to which that user belongs.
  • If the Microsoft Active Directory user is locked out of Microsoft Active Directory, the user will not be locked in APM database.
  • All the settings specified in the User Defaults page, including Time Zone, UOM, Culture, Language, and Site are assigned to new users.
    Note: The default site in the User Defaults page is assigned to new users only if the default site is not configured in the Microsoft Active Directory or in the domain record in LDAP Manager.

About Synchronization and Authentication

APM Security Users are authenticated at log-in. In addition to validating status for a user (whether the Active check box is selected in the Security User record for that user), at log-in, the APM system initializes all the information and permissions for that user. If any of that information changes while the Security User is logged in to the APM system, those changes will not be reflected immediately. The changes will not take effect until the user logs out of APM and then logs back in. This behavior applies to changes made manually and automatically through the LDAP synchronization process. In other words, regardless of when or how often the LDAP synchronization process runs, changes made to a user account will not be applied until the next time a user logs in to the APM system.

About LDAP Authentication and Same Sign-On

LDAP authentication is generally used by Same Sign-On (SSO) systems. The enterprise user logs on initially using a form-based enterprise login screen. The user enters an ID and password, and the SSO software then takes the information and sends it to the security server using an encrypted connection. The security server then logs on to the LDAP server on behalf of the user by providing the LDAP server with the user's ID and password. If successful, the security server then proceeds with any authorization and/or lets the user proceed to the application or resource that he or she wants to access.

About LDAP Log Records

About This Task

To access LDAP Log records, you must enable LDAP integration and logging, and then run the LDAP synchronization process. If you would like detailed Log records related to LDAP to be created, on the LDAP Manager page, you should also select the Enable informational messages check box before running the LDAP synchronization process.

To access LDAP Log records, on the APM Server, navigate to C:\ProgramData\Meridium, and then select the Log file whose file name contains the date that corresponds to the time at which the LDAP synchronization process was run (e.g., Meridium_2015-12-20.txt).

When the LDAP synchronization process begins, the following line of text is added to the Log. Based on the information being synced, the values within brackets will vary.
  • {0} – SyncUsers

When the LDAP synchronization process finishes, the following line of text is added to the Log. Based on the information that was synced, the values within brackets will vary.

  • {0} - Finished SyncUsers. Found {1} actions
Note: If the Enable informational messages check box is cleared when the LDAP synchronization process occurs, the Log records will only contain the records described previously, which define the beginning and end of the LDAP synchronization process.

When the LDAP synchronization process is running, if the Enable informational messages check box is selected, additional LDAP-related records will be added to the Log. In the Log, these additional records will appear between the records described previously, which define the beginning and end of the LDAP synchronization process. The following are examples of additional LDAP-related records that could be created in the Log. This list is not comprehensive.

  • Found {0} domains to process
  • Found {0} users in the {1} domain
  • Found {0} APM users associated with the domain {1}
  • Found {0} actions for the domain {1}

After opening a Log file containing LDAP information, you can use the Find… feature in Notepad to search the Log for instances LDAP-related records (i.e., you could search for syncusers or domains to process to find lines of text containing those terms).

LDAP Workflow

This topic provides a basic workflow for using this module, as well as links to the available procedures, concepts, and reference topics.

Steps

  1. Enable LDAP integration and logging.
    Note: LDAP integration will not be available until it has been enabled.
  2. If you did not select the Enable APM Security check box, determine which existing Microsoft Active Directory Groups you want to map to APM Security Roles, and for each of those Microsoft Active Directory Groups, create a APM Security Role whose name matches exactly a Microsoft Active Directory Group name. When LDAP synchronizes Microsoft Active Directory and APM, each user will be assigned to the APM Security Roles whose names match exactly the names of the Microsoft Active Directory Groups to which they belong. If you selected the Enable APM Security check box, this step is not required, and you will manage Security Role assignment in APM .
  3. Create a Domain record in APM for each Active Directory domain that contains users whose information should be synchronized with records in APM. Domain records store identifying information about the Microsoft Active Directory domains that exist in your organization.
  4. Schedule an LDAP synchronization process to periodically update APM with user information from Microsoft Active Directory.
    Important: After implementing LDAP synchronization, do not modify Security User information in APM; instead, modify the user information in Microsoft Active Directory, and then synchronize. Synchronization overwrites all APM Security User site assignments, Security Role assignments, and all other mapped information with the most recent information in Microsoft Active Directory.

Enable LDAP Integration and Logging

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
  2. On the LDAP Manager page, select the Enable LDAP Integration check box.
  3. If you would like detailed Log records related to LDAP to be created, select the Enable informational messages check box.
    Note: The Enable informational messages check box can be selected only if the Enable LDAP Integration check box is also selected.
  4. If you will manage APM Security Role assignment in APM, rather than via LDAP, select the Enable APM Security check box.
    Note: If you do not select this check box, you must complete step 2 in the LDAP workflow.
  5. If your LDAP is synchronized and you do not want to change your expired Microsoft Active Directory password through the APM login screen, clear the Enable Password Change check box.
    Note: The Enable Password Change check box is selected by default. If your LDAP password expires in the Microsoft Active Directory file system, you will be prompted to change the password when you attempt to log in to APM. If the Enable Password Change check box was not selected during LDAP synchronization and you attempt to log in to APM after your password expires, you will encounter an error. You will then need to contact the Microsoft Active Directory administrator to change the password.
  6. In the upper-right corner of the page, select .
    LDAP integration and logging is enabled.

What To Do Next

About Managing Users When LDAP Integration is Enabled

About This Task

The LDAP integration feature is intended to simplify the APM user management process. It allows you to manage APM users through your existing, primary user management system: Microsoft Active Directory.

User information may change periodically in Microsoft Active Directory (e.g., group assignment, site assignment, address, phone number, job title, etc.).

One advantage of configuring LDAP integration is the ability to synchronize APM Security User records with the information in Microsoft Active Directory. The changes made in Microsoft Active Directory will be reflected in APM after synchronization.

Note:

User Status after LDAP Synchronization

About This Task

When the LDAP synchronization process runs, a APM Security User's status (i.e., whether the Active check box is selected or cleared in the Details section of the Security User record for that user) will be updated based upon various conditions in Microsoft Active Directory.
The Active check box for a APM Security User will be cleared when:
  • The Microsoft Active Directory account for the user is disabled.
  • The user is not assigned to any Microsoft Active Directory Groups.

The Active check box for a APM Security User will be selected automatically after these conditions are resolved in Microsoft Active Directory and the synchronization process runs again.

Create a Domain Record

Procedure

  1. Access the LDAP Page.
  2. In the pane that displays the list of domain records, select .
    The workspace for a new Domain record appears.
  3. In the Name drop-down list box, select the name of the cross domain that contains your Active Directory data.
    Note: The domain names that appear in the Name drop-down list box are configured in the Cross Domains page. For more information, refer to the Configure a New Cross Domain section of the documentation.
  4. If you want users belonging to a particular Microsoft Active Directory Group to be assigned the Super User privileges in APM (that is, you want the Super User check box to be selected in the Details section of the Security User record for that user), then, in the Super User Role box, select the APM Security Role whose name matches the Active Directory Group whose members should be granted Super User privileges in APM.
  5. In APM, each Security User must be assigned to at least one site, and must be assigned to a default site. If you want the default site for each Security User associated with a Domain record to be set to a site during synchronization, then, in the Default Site box, select the site that should be set as the default site.
  6. As needed, in the <domain name> section, enter values in the available fields.
  7. As needed, in the Field Mappings section, enter values in the available fields. The section is populated automatically with LDAP baseline Field Mapping records. To remove a Field Mapping record, in the row for the Field Mapping record that you want to remove, select , and then, in the Confirm Delete dialog box, select Yes. To add a Field Mapping record, in the Field Mappings section, select , then enter values in the available fields, and then, below the row for the new Field Mapping record, select Save.
    Important:

    To successfully log in to APM, Security Users must be assigned to at least one site, and must be assigned to a default site.

    If your APM system contains only one site and you selected a default site in step 4, creating Microsoft Active Directory Groups to map site assignments from Microsoft Active Directory to APM is not required.

    Additionally, you can run the LDAP synchronization process without selecting a default site in the Default Site box or creating the Microsoft Active Directory Groups described in this note. If you do so, APM will assign the first user-created site in the database as the default site for each synchronized user. If no user-created site exists in the database, then the Meridium Default site will be assigned as the default site for each synchronized user.

    To create Microsoft Active Directory Groups to map site assignments from Microsoft Active Directory to APM:

    1. Ensure that you have created, in APM, each site that you want to associate with users during synchronization.
    2. In Microsoft Active Directory, create a Group whose name is <data source>_Default_<site>, where:
      • <data source> is the name of the data source to which you will be connected during synchronization.
      • Default is mandatory text. Microsoft Active Directory users who are associated with this group will be assigned to <site> during synchronization, and will be assigned <site> as their APM default site.
      • <site> is the exact name of a site in APM that you want to assign as the default site for some users during synchronization.

      Ensure that the Microsoft Active Directory Group name matches the naming convention. For example, to assign users the default site Plant, which exists in a data source named Industry, you would create a Microsoft Active Directory Group named Industry_Default_Plant.

    3. In Microsoft Active Directory, if needed, create a Group whose name is <data source>_<site>, where:
      • <data source> is the name of the data source to which you will be connected during synchronization.
      • <site> is the exact name of a site in APM that you want to assign to some users during synchronization. It will not be assigned as the default site for the users.

      Ensure that the Microsoft Active Directory Group name matches the convention. For example, to assign users the site Plant, which exists in a data source named Industry, you would create a Microsoft Active Directory Group named Industry_Plant.

    4. As needed, repeat steps b and c.
    5. In Microsoft Active Directory, associate the Groups with users. Each Microsoft Active Directory user whose information will be synchronized with APM must be associated with exactly one Group whose name is <data source>_Default_<site>. Each user can be associated with any number of additional groups whose names are <data source>_<site>.

      The Groups are assigned to users in Microsoft Active Directory. When you perform an LDAP synchronization, APM site assignments will be made based on the logic described in these steps.

    Note:

    Each APM Security User must have a unique User ID. You can either allow these User IDs to be generated automatically, or you can create a field mapping that will generate User IDs based on the values in a selected Microsoft Active Directory field.

    If you do not create the field mapping described in the steps below, User IDs will still be generated automatically during synchronization. If the userPrincipalName Microsoft Active Directory field has a value, that value will become the APM Security User ID for the user. If the userPrincipalName Microsoft Active Directory field does not have a value, the value in the sAMAccountName Microsoft Active Directory field will become the APM Security User ID for the user.

    If you would like to use a different Microsoft Active Directory field to populate the User IDs of APM Security Users during synchronization:

    1. In Microsoft Active Directory, choose a field that exists for every Microsoft Active Directory user and whose values you want to be used as the APM User IDs for those users.
    2. In APM, for the appropriate Domain record, in the upper-right corner of the Field Mappings section, select .

      A new row appears in the section, containing the LDAP Field and Meridium Field boxes.

    3. In the LDAP Field box, enter the name of the Microsoft Active Directory field that you chose in step a.
    4. In the Meridium Field box, enter USERID, and then, below the row for the new Field Mapping record, select Save.

      The Field Mapping record used to map User IDs is created.

  8. In the workspace, select .
    A new Domain record is created.

What To Do Next

LDAP Domain Records

This topic provides an alphabetical list and description of the fields that exist in Domain records. The information in the table reflects the baseline state and behavior of these fields.

FieldData TypeDescriptionBehavior and Usage
CaptionCharacterA short description of the domain. You can define this value manually to help distinguish this domain from any other domains that you define.
Default SiteCharacterThe default site that will be assigned to new Security Users created during LDAP synchronization.None
RootCharacterThe starting point of the container in which APM will look for user objects in Microsoft Active Directory. The APM system will use this information to find user objects in Microsoft Active Directory.
User FilterCharacterThis filter is used to locate users within the specified directory.This filter is used during the synchronization process to locate Microsoft Active Directory users that belong to a specific group within the domain. You can accept the default value in this field.

LDAP Field Mapping Records

This topic provides an alphabetical list and description of the fields that exist in LDAP Field Mapping records. The information in the table reflects the baseline state and behavior of these fields. For more information on the baseline LDAP Field Mapping records, refer to the LDAP Baseline Field Mapping Records topic.

FieldData Type Description Behavior and Usage
LDAP FieldCharacterThe name of Microsoft Active Directory field that will serve as the source field for mapping. The baseline Field Mapping records that appear in the Domain records by default contain a set of Active Directory fields that are mapped to the corresponding APM fields. However, if you want to create additional Field Mapping records, you can manually define the Active Directory field that you want to map to a reserved APM field. You can obtain a list of available Active Directory fields from Microsoft.
Meridium FieldCharacterThe field ID of the field in APM that will serve as the target field for mapping. The baseline Field Mapping records that appear in the Domain records by default contain a set of Active Directory fields that are mapped to the corresponding APM fields. However, if you want to create additional Field Mapping records, you can use the reserved APM fields to map to the Active Directory fields. You must specify the field ID, not the field caption.

LDAP Baseline Field Mapping Records

This topic provides an alphabetical list and description of the fields that exist in LDAP Baseline Field Mapping records. The information in the table reflects the baseline state and behavior of these fields.

LDAP Field APM FieldNotes
companyMI_HR_COMPANY_CHRNone
departmentMI_HR_DEPT_CHRNone
givenNameMI_HR_FIRST_NAME_CHRNone
lMI_HR_CITY_CHRNone
mailMI_HR_EMAIL_TXNone
postalAddressMI_HR_ADDR1_CHRNone
postalCodeMI_HR_POSTCODE_CHRNone
snMI_HR_LAST_NAME_CHRNone
stMI_HR_STATE_CHRNone
telephoneNumberMI_HR_PHONE1_CHRNone
titleMI_HR_JOB_TITLE_CHRNone
Note: When you configure a custom attribute for Culture or Timezone fields in the Microsoft Active Directory, you can map it to SEUS_CULTURE_ID or SEUS_TIME_ZONE_CHR fields respectively, else the Culture and Timezone values will be set from the User Defaults workspace.

Reserved APM Fields for LDAP Mapping

The following table lists the reserved APM fields that are available for mapping with LDAP fields.

Reserved APM FieldDescriptionNotes
MI_HR_ADDR2_CHRAddress2None
MI_HR_AREA_RESPONSIBILITY_TXAreaOfResponsibilityNone
MI_HR_BADGE_IDBadgeIdNone
MI_HR_BUSINESS_UNIT_TXBusinessUnitNone
MI_HR_COMMENTS_TXCommentsNone
MI_HR_COUNTRY_CHRCountryNone
MI_HR_FAX_CHRFaxNumberNone
MI_HR_MID_INIT_CHRInitialNone
SEUS_LANGUAGE_IDLanguageIdNone
MI_HR_PHONE2_CHRPhoneNumber2None

Remove a Domain Record

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
  2. In the left pane, select the Domain record that you want to remove.
    The workspace for the selected Domain record appears.
  3. In the upper-right corner of the workspace, select .
    The Confirm Delete dialog box appears.
  4. On the Confirm Delete dialog box, select Yes.
    The Domain record is removed.

Run the LDAP Synchronization Process Manually

About This Task

The synchronization process can be managed either by manually running the LDAP synchronization or by scheduling the synchronization process.

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
  2. In the LDAP workspace, select Run LDAP Sync.
    The Run LDAP Sync dialog box appears.
  3. Select Yes.
    The LDAP synchronization is run.

Schedule an LDAP Synchronization Process

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
  2. In the LDAP workspace, in the LDAP's Job Schedule section, select .
    The Edit Schedule window appears. Enter the values in the required fields. For more information on creating a schedule, see Schedule a Job.

    In the LDAP's Job Schedule section, the job schedule item appears.

  3. Beside the job schedule item, select .
    The job schedule item is saved.
  4. If you want to receive email about the failed scheduled job, select the Notify when LDAP job fails check box.
    The + users/group link appears. You can select this link to select the users or groups to whom you want to send the email notification.
  5. Select the + users/group link and in the Select users or group window, select the names of the users or groups.
    The names of the selected users or groups appear. When a scheduled job fails, an email will be sent to these users or groups.

Results

  • When the job schedule item is active, the synchronization will be executed based on the defined schedule.

Configure Notifications for the Failed LDAP Jobs

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
    The LDAP page appears.
  2. Select the Enable Notification When LDAP Job Fails check box.
    The + User/Group link appears.
  3. Select the + User/Group link.
    The Select users or group window appears, displaying a list of users in the User section.
  4. In the User section, select the Security Users whom you want to notify when a scheduled LDAP synchronization job fails, and then select OK.
    Note: If you want to notify the groups, select the appropriate groups in the Group section.
    The Select users or group window disappears and the names of the selected users or groups appear in the LDAP page. When a scheduled LDAP synchronization job fails, the selected users or groups are notified.

Remove an LDAP Synchronization Job Schedule Item

Procedure

  1. In the Applications menu, navigate to ADMIN > Security Manager > LDAP.
  2. In the LDAP workspace, in LDAP's Job Schedule section, beside the job schedule item that you want to remove, select .
    The LDAP dialog box appears.
  3. Select Yes.
    The job schedule item is removed.

Deactivate Security User Accounts

About This Task

This task describes how to deactivate a security user account that is not associated with any Security Groups in APM but the corresponding user account in Microsoft Active Directory is active.

Procedure

  1. Access the LDAP page.
  2. In the LDAP page, in the pane that displays a list of APM domains, select the domain for which you want to deactivate the security user accounts.
    The <Domain Name> workspace appears.
  3. In the User Filter box, make sure that all the active security user accounts in APM appear in the user filter query.
    Note: If an active user account is not available in the user filter query, the user account is deactivated.
  4. In the LDAP Sync Domain Settings drop-down list box, select Deactivate Unsynced Users.
  5. Select .
    The Security User accounts are deactivated.