LDAP Connection Setup

As a system administrator, you set up the LDAP connection and configure your Client and Users to use LDAP to authenticate login data.

Notes:

  • An LDAP login via the AE is only possible if the password includes characters of the code table you use in your respective database.

  • External password checks made via the AE Program Exit are called prior to the LDAP connection, see Password Exit.

This page includes the following:

Prerequisites

Using LDAP to authenticate login data is not set by default and is only possible if the LDAP key in the UC_SYSTEM_SETTINGS variable is set to Y. For more information, see LDAP and UC_SYSTEM_SETTINGS - Systemwide Settings.

To use an Active Directory (AD) or Oracle Directory Server (ODS) with LDAP over TLS/SSL, you have to configure the keystore for the Java work process (JWP) and make sure that the certificates that the JWP requires are stored in the keystore. In an on-premises environment, using a TLS/SSL connection is optional. In AAKE you can only use LDAP over TLS/SSL.

How you establish a TLS/SSL connection to the LDAP server differs depending on the type of environment that you use. For more information, see below.

TLS/SSL Connection - Configuring the JWP Keystore and Adding Certificates

This section provides information on how to set up the JWP keystore and add the certificates for all environment types.

Automic Automation On-Premises

Using TLS/SSL to secure the connection to the LDAP server on an on-premises environment is optional. On-premises environments provide different options for configuring the keystore and adding the certificates.

To use TLS/SSL, the certificate(s) of the LDAP server must be available to the Java Work Process (JWP). The JWP uses the default keystore file cacerts in the lib/security directory of the JRE.

There are a number of keystore file configuration options:

  • Using an alternative keystore file:

    If you want the JWP(s) to use an alternative keystore file, you have to define the file name and path to a centrally stored file in the JWP_KEYSTORE_PATH key in the UC_SYSTEM_SETTINGS variable. In case the defined path is not accessible or invalid, a log message will be written to the default log location and the JWP will use the default keystore file. For more information, see JWP_KEYSTORE_PATH.

  • Creating an individual keystore file using the JWP:

    If you want to use an individual keystore file, you can create it using the following command:

    java -jar ucsrvjp.jar -installcert host:port keystorePath

    In case the defined path in keystorePath does not exist, the JWP creates a new keystore file in that location. You can then define a password for that keystore file.

  • Using an alternative password for keystore file access:

    The default password used by the JWP is the default password of the JRE keystore. If you want the JWP to use a different password, you have to define a Login object containing that password by following these steps:

    • Create a Login object (or use an existing one).
    • Use the JWP_KEYSTORE_LOGIN key in the UC_SYSTEM_SETTINGS variable to enter the name of that Login object. For more information, see JWP_KEYSTORE_LOGIN.
    • Open the referenced Login object, select the Login page and add a new row there.
    • In the column Name, select "*", in the column Type select JWP_KEYSTORE.
    • The Login info is optional for this function, but as this column cannot be empty by default, you have to enter something here.
    • Enter the password you chose for the keystore file.

You also have to make sure that the certificates are saved in the keystore. There are different options:

  1. Add certificates using the keytool.

    1. To use the default keystore of the JRE, go to the jre\lib\security folder of the Java installation and import the certificate with the keytool command:

      2. keytool -keystore cacerts -importcert -alias ldapServer -file certficate.cer

    2. To use your own keystore file defined in the UC_SYSTEM_SETTINGS variable using the JWP_KEYSTORE_PATH key, go to the defined path and import the certificate with the keytool command:

      3. keytool -keystore <keystore> -importcert -alias ldapServer -file certficate.cer

      When prompted to trust this certificate respond by typing "Y".

      For more information, see JWP_KEYSTORE_PATH.

  2. Add certificates via download.

    1. Another option to install the certificate is the command line parameter -installcert of the Java Work Process.

      2. java -jar ucsrvjp.jar -installcert <host>:<sslport>

      • This assumes that the Java Work Process has write access to the cacerts file of the Java installation.
      • This command detects the path of cacerts, connects to the specified host and port and tries to create a TLS/SSL connection.
    2. This command to add a certificate via download will set an optional parameter for the file name of the keystore:

      3. java -jar ucsrvjp.jar -installcert <host>:<sslport> <keystorePath>

    Notes:

    • When the parameter JWP_KEYSTORE_PATH is valid but the file doesn't exist, JWP creates a new keystore file in the same location. For more information, see JWP_KEYSTORE_PATH. During this process the user can define an individual password.

    • If a certificate is missing, the message "unable to find valid certification path to requested target" is printed and the missing certificate is downloaded and stored in the cacerts file.

AAKE

Before installing AAKE, you have to configure the JWP keystore, in which the keystore file will be stored and create the jwp-keystore Kubernetes secret so that the keystore file can be passed on to the LDAP server. To do so, follow the steps listed below:

  1. Add the certificate to the keystore using a keytool.

    1. To use the default keystore of the JRE, go to the jre\lib\security folder of the Java installation and import the certificate with the keytool command:

      2. keytool -keystore cacerts -importcert -alias ldapServer -file certficate.cer

    2. To use your own keystore file defined in the UC_SYSTEM_SETTINGS variable using the JWP_KEYSTORE_PATH key, go to the defined path and import the certificate with the keytool command:

      3. keytool -keystore <keystore> -importcert -alias ldapServer -file certficate.cer

      When prompted to trust this certificate respond by typing "Y".

      For more information, see JWP_KEYSTORE_PATH.

  2. Configure the JWP keystore. To do so, create the jwp-keystoreKubernetes secret to pass the keystore file on to the LDAP server. You can do so by using the following kubectl command:

    kubectl create secret generic jwp-keystore --from-file ./cacerts

    After installing AAKE, if the jwp-keystore secret exists, it is automatically mounted in all JWP pods using the default path '/usr/server/bin/secrets/jwp-keystore/cacerts.

Configuring Clients and Users to Use LDAP

To configure the connection, you first need to configure your Clients:

  1. Log on to system Client 0.

  2. Switch to the DIV_VARIABLES folder and duplicate the UC_LDAP_EXAMPLE variable, see UC_LDAP_EXAMPLE - LDAP Connection Variable.

  3. Rename the duplicate:

    • Active Directory: Rename the copy to UC_LDAP_Domain. For example, if the domain name is SMITH, the variable should be called UC_LDAP_SMITH.

    • Oracle Directory Server: User object names are composed of name and department. Rename the copy to UC_LDAP_department. Each department requires its own variable. Using this method requires the domain to be specified in the DOMAIN_ALIAS key.

  4. Open the newly duplicated variable and define the connection data to meet your needs.

    Example 

    VERSION = 2
TLS = Y 
USE_DISTINGUISHED_NAME = Y
SERVER = <hostname>:<tlsport>

    The default port for TLS/SSL is 636.

    Note: Instead of using the standard user search with the USE_DISTINGUISHED_NAME key, you can define the SEARCH_FILTER key. For more information, see UC_LDAP_EXAMPLE - LDAP Connection Variable.

  5. Save and close the variable.

Once the Client configuration is done, you need to set up the LDAP connection in the User object:

  1. Create a User object or rename an existing one and define the name of the User object, see Users (USER).

    • Active Directory: If the distinguished name (DN) is not being used, the User object must have the same name as the user in the Active Directory. The name is composed of the user name and the domain. For example, SMITH/AE.

    • Oracle Directory Server: The User object must have the same name as the user's distinguished name. The synchronization of data only works if the uid and the name of the User object are identical. For example, uid=nga, ou=people, dc=example, dc=com, thus the name of the User object must be NGA/DEPARTMENT.

  2. Open the User object.

  3. Activate the LDAP connection checkbox.

    The input fields First name, Last name, Email1, and Email2 are locked. Their contents are filled with LDAP data from the respective server, when the synchronization is started.

    Note: The Active Directory (AD) does not use the second email address. It can be used if required.

  4. Save and close the User object.

  5. Repeat all steps for additional users.

Important! Information stored in the User object is only updated while logging on or when using the Synchronize data with LDAP now button. There is no automatic synchronization and it only works if the user that synchronizes the data already is an LDAP user. This means that the user has already logged off the Automic Web Interface after being activated for LDAP and has logged on again (thus has been synchronized).

User Credentials and (Optionally) Login Object

Your User credentials allow you to perform an LDAP synchronization, as long as the User was logged in with LDAP. When you set up your own User for LDAP for the first time, you need to log off the system and log in again to enable the data synchronization.

Once logged in, you can use the Synchronize data with LDAP now button for the synchronization.

However, if the LDAP Server is set up in a way that does not allow your User to search for other users, you have the option of creating a second (technical) User object with the sole purpose of carrying out the LDAP synchronization. You define the User as described above.

You also have the option of installing and configuring LDAP Sync to keep user objects in sync with the AD/ODS user base, see LDAP Sync - Synchronizing LDAP and Automic system Users.

If you decide to create a second (technical) User, it must also exist in LDAP and the LDAP administrator needs to grant it the relevant rights for the LDAP server.

In this case, you also need to create a Login object for the second (technical) User, see Login (LOGIN).

Once User and Login object have been defined, you need to register the new Login object in the already existing UC_LDAP_XXXX variable by using the SYNC_LOGIN key, see UC_LDAP_EXAMPLE - LDAP Connection Variable.

To do so, do the following:

  1. Create a Login object in Client 0 that includes the credentials required to connect to the LDAP server:

    1. Set Agent/Name to *

    2. Set type to LDAP.

    3. In Username/ID, enter the name or distinguished name of the user to use when communicating with the LDAP server.

    4. In the password field, enter the User's password.

  2. Register this new Login object in the already existing UC_LDAP_XXXX variable by using the SYNC_LOGIN key, see UC_LDAP_EXAMPLE - LDAP Connection Variable.

  3. Test whether the SYNC_LOGIN setting and the specified Login object are configured correctly. To do so:

    1. Log into AWI using a non-LDAP user.

    2. Open or create a User object that corresponds to an LDAP user.

    3. Make sure that the LDAP connection option is enabled.

    4. Click Synchronize data with LDAP now.

    5. If everything is set up correctly, the distinguished name (DN) of the user will automatically be retrieved from the LDAP server.

If the SYNC_LOGIN key is not specified in the UC_LDAP_XXX variable, or the Login object does not exist, the credentials of the current user apply.

See also: