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. GE Digital 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 GE Digital 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 GE Digital 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 GE Digital APM user records. The mappings that are defined in LDAP Mapping records are used to synchronize data between Microsoft Active Directory and GE Digital APM. The LDAP Mapping records determine what information should be retrieved from Microsoft Active Directory and where it should be stored in GE Digital APM. Each LDAP Mapping record contains the field LDAP Field, which defines the source field in Microsoft Active Directory, and the Meridium Field, which defines the target field in GE Digital APM. Whenever synchronization occurs, data will be pulled from the source field (defined by the value in the LDAP Field field) and used to populate the value in the target field (defined by the Meridium Field field).

An LDAP Mapping record must exist for each Microsoft Active Directory field that you want to map to a GE Digital APM field. GE Digital APM provides a set of baseline LDAP Mapping records that map standard Microsoft Active Directory fields to fields in GE Digital APM. If you want to map additional information to GE Digital APM, you will need to add additional Field Mapping records. If you want to change the mappings that are defined through the baseline records, you can modify the records as needed.

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 GE Digital APM, and update the corresponding Security User records. When the synchronization process is run, GE Digital APM Security User properties and status will be updated to reflect the last saved information in Microsoft Active Directory.

Note: To ensure that your GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital APM system will retrieve the information for the Microsoft Active Directory users associated with the Microsoft Active Directory domains that have been defined in GE Digital APM. The corresponding Security User records will be updated. Fields in GE Digital APM will be updated with the information in Microsoft Active Directory using LDAP Field Mapping records.
If the GE Digital APM system finds a user in Microsoft Active Directory who does not have a corresponding Security User record in GE Digital APM:
- A Security User record will be created in the GE Digital 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 GE Digital 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 GE Digital APM Security Role whose name does not match exactly the name of a Microsoft Active Directory Group to which that user belongs.

About Synchronization and Authentication

GE Digital 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 GE Digital 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 GE Digital APM system, those changes will not be reflected immediately. The changes will not take effect until the user logs out of GE Digital 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 GE Digital 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 GE Digital 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).

Access the LDAP Page

Procedure

In the module navigation menu, select Admin > Security Manager > LDAP.

The LDAP page appears.

What To Do Next

Enable LDAP Integration and Logging.

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

Enable LDAP integration and logging.
Note: LDAP integration will not be available until it has been enabled.
If you did not select the Enable APM Security check box, determine which existing Microsoft Active Directory Groups you want to map to GE Digital APM Security Roles, and for each of those Microsoft Active Directory Groups, create a GE Digital APM Security Role whose name matches exactly a Microsoft Active Directory Group name. When LDAP synchronizes Microsoft Active Directory and GE Digital APM, each user will be assigned to the GE Digital 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 GE Digital APM .
Create a Domain record in GE Digital APM for each Active Directory domain that contains users whose information should be synchronized with records in GE Digital APM. Domain records store identifying information about the Microsoft Active Directory domains that exist in your organization.
Schedule an LDAP synchronization process to periodically update GE Digital APM with user information from Microsoft Active Directory.
Important: After implementing LDAP synchronization, do not modify Security User information in GE Digital APM; instead, modify the user information in Microsoft Active Directory, and then synchronize. Synchronization overwrites all GE Digital 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

In the module navigation menu, select Admin > Security Manager > LDAP.
On the LDAP Manager page, select the Enable LDAP Integration check box.
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.
If you will manage GE Digital APM Security Role assignment in GE Digital 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.
If you do not want the GE Digital APM login password to expire, clear the Enable Password Change check box.

Note: By default, the Enable Password Change check box is selected. Therefore, when your password expires after thirty days in the Microsoft Active Directory file system, you will be prompted to change the password at the time of logging in to GE Digital APM. If you clear the check box, the password will never expire.
In the upper-right corner of the page, select .
LDAP integration and logging is enabled.

What To Do Next

Create a Domain Record.

About Managing Users When LDAP Integration is Enabled

About This Task

The LDAP integration feature is intended to simplify the GE Digital APM user management process. It allows you to manage GE Digital 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 GE Digital APM Security User records with the information in Microsoft Active Directory. The changes made in Microsoft Active Directory will be reflected in GE Digital APM after synchronization.

Note:

If you did not select the Enable APM Security check box, Security Role assignment will not be modified during synchronization, and you will manage Security Role assignment in GE Digital APM .
LDAP integration is designed to ensure that these the systems (GE Digital APM and Microsoft Active Directory) are synchronized. Always be sure to follow the recommended workflow for managing users.

User Status after LDAP Synchronization

About This Task

When the LDAP synchronization process runs, a GE Digital 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 GE Digital APM Security User will be cleared when:

The Microsoft Active Directory account for the user is inactive.
The password for the user has expired.
The user is locked out of Microsoft Active Directory.

The Active check box for a GE Digital 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

Access the LDAP Page.
In the pane that displays the list of domain records, select .
The workspace for a new Domain record appears.
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.
If you want users belonging to a particular Microsoft Active Directory Group to be assigned the Super User privileges in GE Digital 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 GE Digital APM Security Role whose name matches the Active Directory Group whose members should be granted Super User privileges in GE Digital APM.
In GE Digital 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.
As needed, in the <domain name> section, enter values in the available fields.
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 GE Digital APM, Security Users must be assigned to at least one site, and must be assigned to a default site.

If your GE Digital 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 GE Digital 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, GE Digital 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 GE Digital APM:
1. Ensure that you have created, in GE Digital 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 GE Digital APM default site.
  - <site> is the exact name of a site in GE Digital 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 GE Digital 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 GE Digital 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, GE Digital APM site assignments will be made based on the logic described in these steps.
Note:
Each GE Digital 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 GE Digital 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 GE Digital 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 GE Digital 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 GE Digital APM User IDs for those users.
2. In GE Digital 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.
In the workspace, select .
A new Domain record is created.

What To Do Next

Schedule an LDAP Synchronization Process.

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.


Field	Data Type	Description	Behavior and Usage
Caption	Character	A short description of the domain.	You can define this value manually to help distinguish this domain from any other domains that you define.
Default Site	Character	The default site that will be assigned to new Security Users created during LDAP synchronization.	None
Root	Character	The starting point of the container in which GE Digital APM will look for user objects in Microsoft Active Directory.	The GE Digital APM system will use this information to find user objects in Microsoft Active Directory.
User Filter	Character	This 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.


Field	Data Type	Description	Behavior and Usage
LDAP Field	Character	The name of Microsoft Active Directory field that will serve as the source for the mapping.	For each LDAP field that you want to map to a GE Digital APM field, you must define the LDAP field manually You can obtain a list of available Active Directory fields from Microsoft.
Meridium Field	Character	The field ID of the field in GE Digital APM that will serve as the target field for the mapping.	For each GE Digital APM field to which you want an LDAP field to map, you must define the GE Digital APM field manually. The field can belong to any family, but you will probably want to specify a field that is defined in the Human Resource family or the Security User family. Be sure to 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	GE Digital APM Field	Notes
company	MI_HR_COMPANY_CHR	None
culture	SEUS_CULTURE_ID	If the LDAP Field value does not match a valid GE Digital APM culture value, the culture en-US will be used.
department	MI_HR_DEPT_CHR	None
givenName	MI_HR_FIRST_NAME_CHR	None
l	MI_HR_CITY_CHR	None
mail	MI_HR_EMAIL_TX	None
postalAddress	MI_HR_ADDR1_CHR	None
postalCode	MI_HR_POSTCODE_CHR	None
sn	MI_HR_LAST_NAME_CHR	None
st	MI_HR_STATE_CHR	None
telephoneNumber	MI_HR_PHONE1_CHR	None
timeZone	SEUS_TIME_ZONE_CHR	If the LDAP Field value does not match a valid GE Digital APM time zone value, the default time zone specified on the User Defaults page will be used.
title	MI_HR_JOB_TITLE_CHR	None

Remove a Domain Record

Procedure

In the module navigation menu, select Admin > Security Manager > LDAP.
In the left pane, select the Domain record that you want to remove.
The workspace for the selected Domain record appears.
In the upper-right corner of the workspace, select .
The Confirm Delete dialog box appears.
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

In the module navigation menu, select Admin > Security Manager > LDAP.
In the LDAP workspace, select Run LDAP Sync.
The Run LDAP Sync dialog box appears.
Select Yes.
The LDAP synchronization is run.

Schedule an LDAP Synchronization Process

Procedure

In the module navigation menu, select Admin > Security Manager > LDAP.
In the LDAP workspace, in the LDAP's Job Schedule section, select .
The Edit Schedule window appears.
Select either the One time or Recurrence check box.
In the Time Zone box, select the time zone in which you want the first scheduled execution to occur.
In the Start box, specify the date and time at which you want the first scheduled execution to occur.
If you selected the Recurrence check box, in the Every section, specify the frequency at which you want the synchronization to occur.
If you selected the Recurrence check box, in the End section, specify when the recurring synchronization should end.
Select OK.
In the LDAP's Job Schedule section, the job schedule item appears.
Beside the job schedule item, select .
The job schedule item is saved.
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.
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

In the module navigation menu, select Admin > Security Manager > LDAP.
The LDAP page appears.
Select the Enable Notification When LDAP Job Fails check box.
The + User/Group link appears.
Select the + User/Group link.
The Select users or group window appears, displaying a list of users in the User section.
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

In the module navigation menu, select Admin > Security Manager > LDAP.
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.
Select Yes.
The job schedule item is removed.