UAA LDAP Integration Configuration Tool
The UAA LDAP Integration Configuration Tool is a GUI based tool that helps users easily configure or reconfigure the various aspects of LDAP integration with UAA after Historian has been installed. In the following sections, we describe how this tool should be used.
This tool is located under C:\Program Files\GE Digital\UAA\ folder. Find uaa-ldap-config-tool.exe and run it with the administrators privilege (right-click and select Run as Administrator). The first screen should look similar to the following:
Note that on this screen most of the fields are read-only and meant only for informational purposes. They identify the URL of the Historian UAA instance to configure, the yml file that this UAA instance uses as the primary configuration file (and that the tool will modify), and a trust store file that the tool will place a server certificate into, when the user selects LDAPS protocol and provides a certificate file.
The tool does ask for the secret of the admin client for UAA, if the user wants to view and/or change mappings from LDAP groups to the pre-defined UAA scopes related to Historian functions. Do note, however, that this field is optional if the user doesnt need to view or change the mappings.
Click the Next button to view the next screen, which should be something similar to the following:
First the user can elect to enable or disable LDAP as an identity provider for UAA by checking or clearing the checkbox at the top labelled Enable LDAP as an Identity Provider for UAA.
If LDAP integration is enabled as an identity provider for UAA, then the following fields should be configured/re-configured:
| Field Name | Remarks |
| LDAP Server URL | URL of the LDAP server, starting with ldap:// or ldaps://. Note that the port number should be specified if a non-standard port is used. |
| Service Account DN | Distinguished name of a service account used to search for users and retrieve usersgroup information. |
| Service Account Password | Password of the service account. Leave it blank, if it does not have to be updated. |
| Search Base | Base of the LDAP directory where search begins. |
| Search Filter | Matching criterion used to identify user. It should match user's input, denoted as {0}, against an LDAP attribute. |
The bottom section only applies when LDAPS (i.e., LDAP on SSL) protocol is used. The fields inside this section grey out when the protocol specified in the LDAP Server URL field is not LDAPS. Otherwise, the user can choose between two options:
-
- Skip LDAP servers certificate verification. While still encrypting all communications between UAA and the LDAP server, this is a less secure option as UAA will not attempt to verify the specified LDAP servers identity and thus is vulnerable to identity-spoof attacks. With this option, the user doesnt need to provide the LDAP servers certification if this option is selected. This option is generally useful during initial provisioning or troubleshooting.
- Enable the use of LDAP servers SSL certificate to verify its identity. In this case, the user should:
- (i) select a certificate alias, which is solely used for uniquely identifying the certificate in the trust store file used by UAA, and
- (ii) provide the LDAP servers certificate in either binary or base 64-encoded form, typically in a file with extension .cer, .crt,.der, or .pem. Use the [] button to open a dialog box to select the certificate file.
Later the tool will import the certificate into the trust store used by UAA and configure the UAA to use this certificate for the purpose of protecting LDAP communications.
IMPORTANT NOTES:
- Selecting and importing the certificate only needs to take place once. When the user re-runs the tool to reconfigure something else, the alias in step (i) above should remain unchanged, and step (ii) doesnt have to be repeated.
- If the user has erroneously selected a certificate file and now wants to cancel the importing, click the Clear button to clear out the file path displayed.
Once the basic LDAP settings have been provided or updated, the user can click on the Next button to move onto the next screen, which has the settings related to how the UAA user accounts group member search is conducted and how LDAP groups map to UAA scopes. It should look similar to the screen below:
The fields displayed/editable are as follows:
| Field Name | Remarks |
| Search Base | Specifies the part of the directory tree under which group searches should be performed. |
| Search Filter | Matching criterion for group membership search for user. |
| Max Search Depth | How many levels deep nested LDAP groups should be searched for to determine users group membership. |
| Search Subtree | Whether the sub-tree of the search base in the LDAP directory should be searched as well. |
The bottom section allows the user to view and edit the group mappings from LDAP groups to each of the pre-defined Historian scopes in UAA. Each row requires the distinguished names of the LDAP groups mapped to the scope. When there are multiple distinguished names for a scope, separate them by a semicolon.
Once this screen is populated, the user can click the Commit button to commit all the changes to the system. A result screen will appear, which should report whether the committing has been successful or not. If for some reason committing failed, it is possible to click the Prev button to change the settings and commit again. Otherwise, the user can click the Close button to close the tool.