Enabling LDAP Authentication

To enable LDAP authentication, configure LDAP connection information in the Control Hub security configuration file, $DPM_CONF/security-app.properties.

1. In the security-app.properties file, enable LDAP authentication by completing the following steps:
   1. Comment out the userGroupProvider.id=embedded line, as follows:

      #userGroupProvider.id=embedded

      When the property is enabled and set to embedded, Control Hub uses either the built-in Control Hub authentication method or the SAML authentication method. Organization administrators configure these authentication methods for each organization.

   2. Uncomment the second userGroupProvider.id property, as follows:

      userGroupProvider.id=M

      Do not change the value of this property.

2. Configure the following global properties used by all LDAP configurations included in the file:

   Global Property	Description
   userGroupProvider.M.providerClass	Do not change this value.
   userGroupProvider.M.multi.ids	Unique ID for each LDAP configuration. The ID can be any string value. To include multiple LDAP configurations, use a comma-separated list. For example, if you want to connect to both a Microsoft Active Directory server and to an OpenLDAP server, you might define the property as follows: userGroupProvider.M.multi.ids=AD,OpenLDAP Default is L.
   userGroupProvider.M.multi.fetchGroups	Retrieves group information from the provider. Must be true if you map Control Hub groups to the provider groups. Default is true.
   userGroupProvider.M.multi.allGroupsProviderId	Set to the same value as the userGroupProvider.M.multi.ids property.

3. Configure the following properties for each LDAP configuration.

   Each LDAP property includes the following prefix:

   userGroupProvider.M.multi.<ID>.ldap

   When you configure the properties, replace the <ID> variable in each property name with the unique ID that you defined for the LDAP configuration. For example, if you defined both AD and OpenLDAP as IDs to create multiple LDAP configurations, then you would replace the <ID> variable in the first three properties as follows:

   # Connection information for Active Directory
   userGroupProvider.M.multi.AD.providerClass=
            com.streamsets.apps.security.authentication.ldap.LdapUserGroupProvider
   userGroupProvider.M.multi.AD.ldap.poolMinConnections=3
   userGroupProvider.M.multi.AD.ldap.poolMaxConnections=10
   
   ...
   
   # Connection information for OpenLDAP
   userGroupProvider.M.multi.OpenLDAP.providerClass=
           com.streamsets.apps.security.authentication.ldap.LdapUserGroupProvider
   userGroupProvider.M.multi.OpenLDAP.ldap.poolMinConnections=3
   userGroupProvider.M.multi.OpenLDAP.ldap.poolMaxConnections=10
   
   ...

   For simplicity, the table below has dropped the following prefix from each LDAP property:

   userGroupProvider.M.multi.<ID>.ldap

   Global Property	Description
   providerClass	Use the correct <ID> variable in the property prefix, but do not change the property value.
   poolMinConnections	Minimum number of connections for the Bind DN connection pool. Default is 3.
   poolMaxConnections	Maximum number of connections for the Bind DN connection pool. Default is 10.
   poolValidateConnections	Validate the connections retrieved from the Bind DN connection pool. Default is true.
   connectionTimeoutMillis	Connection timeout in milliseconds. Default is 5000.
   responseTimeoutMillis	Response timeout in milliseconds. Default is 5000.
   hostname	LDAP server host name.
   port	LDAP server port. To use unencrypted connections or to use connections secured with StartTLS, enter the LDAP port number, typically 389. To use connections secured with LDAPS, enter the port number for secure connections, typically 636.
   ldaps	Secure LDAP connections using the LDAPS (LDAP over SSL) protocol. Default is false. You must complete additional steps to use LDAPS, see Configuring Secure Connections to LDAP.
   startTLS	Secure LDAP connections using the StartTLS protocol. Default is false. You must complete additional steps to use StartTLS, see Configuring Secure Connections to LDAP. Note: StartTLS and LDAPS cannot be used at the same time. If both startTLS and ldaps are set to true, startTLS takes precedence.
   userBaseDn	Base DN under which user accounts are located.
   userObjectClass	Name of the user object class. Default is inetOrgPerson.
   userNameAttribute	Name of the user ID attribute. Default is uid.
   userEmailAttribute	Name of the email address attribute. Default is mail.
   userFullNameAttribute	Name of the user full name attribute. Default is cn.
   userFilter	User attribute used to log in to Control Hub. For example, LDAP users can log in using a username, uid, or email address. Default is %s={user}, where %s is replaced with the value of the userNameAttribute property.
   bindDn	Root distinguished name (DN) used to query the directory server. This user must have privileges to search the directory.
   bindPassword	Password for the root distinguished name. To protect the password, store the password in an external location and then use a function to retrieve the password.
   fetchGroups	Retrieves group information from the LDAP provider. Must be true if you map Control Hub groups to LDAP groups. Default is true.
   groupBaseDn	Base DN to search for group membership.
   groupObjectClass	Name of the group object class. Default is groupOfUniqueNames.
   groupMemberAttribute	Name of the group attribute for user names. Default is uniqueMember.
   groupNameAttribute	Name of the attribute for group names. Default is cn.
   groupFullNameAttribute	Name of the group attribute included with the group display name. Default is description.
   groupFilter	Group attribute used to look up the group memberships for a user. For example, you can search for a user's groups using a base DN, username, or uid. Default is %s={dn}, where %s is replaced with the value of the groupMemberAttribute property. The group object class is also automatically added to the group filter.

4. To configure Control Hub to automatically create and deactivate users to match LDAP groups, edit the following properties:

   Property	Description
   ldap.automaticResolutionEnabled	Enables Control Hub to automatically create and deactivate users to match users in LDAP groups. Set to true.
   ldap.resolutionFrequencyMillis	Number of milliseconds between checks for users to create or deactivate. Default value is 5 minutes. You can set to a larger value, if desired.

5. Shut down and then launch Control Hub again to enable the changes.

1. In the $DPM_CONF/security-app.properties file, set one of the following properties to true:
   • userGroupProvider.M.multi.<ID>.ldap.ldaps
   • userGroupProvider.M.multi.<ID>.ldap.startTLS

   By default, both properties are false and so Control Hub makes unencrypted connections to the LDAP server. If you set both properties to true, StartTLS takes precedence.

2. Set the port property in the security-app.properties file as required, based on the method that you enabled:
   • LDAPS - Use the port number for secure connections, typically 636.
   • StartTLS - Use the LDAP port number, typically 389.
3. If the LDAP server certificate is signed by a private CA or not trusted by the default Java truststore, create a custom truststore file or modify the default Java truststore file to add the CA to the file. Then configure Control Hub to use the modified truststore file.

   By default, Control Hub uses the Java truststore file located in $JAVA_HOME/jre/lib/security/cacerts. If your certificate is signed by a trusted CA that is included in the default Java truststore file, you do not need to create a truststore file and can skip this step.

   In these steps, we show how to modify a copy of the default truststore file to add an additional CA to the list of trusted CAs. If you prefer to create a custom truststore file, see the keytool documentation.

   Note: If you've already configured Control Hub to use a custom truststore file to enable HTTPS, then simply add this additional CA to the same modified truststore file that you created in Step 2. Create a Truststore File.
   1. Use the following command to set the JAVA_HOME environment variable:

      export JAVA_HOME=<Java home directory>

   2. Use the following command to set the DPM_CONF environment variable:

      export DPM_CONF=<Control Hub configuration directory>

      For example, for an RPM installation use:

      export DPM_CONF=/etc/dpm

   3. Use the following command to copy the default Java truststore file to the Control Hub configuration directory:

      cp "${JAVA_HOME}/jre/lib/security/cacerts" "${DPM_CONF}/truststore.jks"

   4. Use the following keytool command to import the CA certificate into the truststore file:

      keytool -import -file <LDAP certificate> -trustcacerts -noprompt -alias <LDAP alias> -storepass <password> -keystore "${DPM_CONF}/truststore.jks"

      For example:

      keytool -import -file  myLDAPServer.pem -trustcacerts -noprompt -alias MyLDAPServer -storepass changeit -keystore "${DPM_CONF}/truststore.jks"

   5. Define the following options in the DPM_JAVA_OPTS environment variable:
      • javax.net.ssl.trustStore - Path to the truststore file on the Control Hub machine.
      • javax.net.ssl.trustStorePassword - Truststore password.

      Modify environment variables in the file required by your installation type.

      For example, define the options as follows:

      export DPM_JAVA_OPTS="${DPM_JAVA_OPTS} -Djavax.net.ssl.trustStore=/etc/dpm/truststore.jks -Djavax.net.ssl.trustStorePassword=mypassword 
      -server -Xmx1024m -Xms1024m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=./dpm-$$-outOfMem.hprof -XX:ErrorFile=./dpm-$$-error.log"

      Or to avoid saving the password in the export command, save the password in a text file and then define the truststore password option as follows: -Djavax.net.ssl.trustStorePassword=$(cat passwordfile.txt)

4. Shut down and then launch Control Hub again to enable the changes.