This chapter gives further guidance on how to configure Active Directory integration to Ubisecure CustomerID.

Preliminary Tasks

Ubilogin Organization

You should first create a root organization in AD for Ubisecure CustomerID data. Traditionally the root organization has been called Ubilogin.

SSL Certificate

The usage of SSL is required when making the LDAP connection from Ubisecure SSO to Active Directory. First the SSL certificate needs to be created for example by using the Microsoft Certificate Authority. Then it needs to be added to both the Ubisecure SSO and Ubisecure CustomerID servers by adding it to the trusted certificates in the Java Runtime Environments.
In Windows the Java certificate storage is by default in the following file:

%JRE_HOME%\lib\security\cacerts

The Active Directory certificate can be added to the Java certificate store using the keytool command. Here are example commands for Windows and Linux installations:

Listing 1. Windows

cd %JRE_HOME%\lib\security
set keytool="%JRE_HOME%\bin\keytool"
%keytool% -importcert -keystore cacerts -trustcacerts -alias mytrustedca -file <insert filename here> -storepass changeit

Listing 2. Linux

cd $JRE_HOME/lib/security
keytool -importcert -keystore cacerts -trustcacerts -alias mytrustedca -file <insert filename here> -storepass changeit

AD Integration User

A dedicated user should be created in Active Directory that can administer everything under the created Ubilogin organization.

CustomerID Directory

The directory service named CustomerID Directory is used to define the configuration used when establishing connections to Active Directory. Prior to Ubisecure CustomerID version 3.7.0 there was a separate file named ad_jndi.properties in the custom directory for the same purpose but that file is no longer read and should be removed. The directory service is still configured quite similarly as a JNDI properties file is written.

Listing 3. Example AD Specific Configuration Strings

java.naming.provider.url = ldaps://ad.example.com/ou=Ubilogin,dc=ad,dc=example,dc=com 
java.naming.security.authentication = simple
java.naming.security.principal = cn=UbiUser,cn=Users,dc=ad,dc=example,dc=com 
java.naming.security.credentials = secret 
java.naming.security.protocol = ssl
java.naming.ldap.attributes.binary = objectGUID
policy.password.protocol = ActiveDirectoryDs
com.ubisecure.util.ldap.server.list = ldaps://server1/ ldaps://server2/ 
com.ubisecure.util.ldap.failover.type = single-master

java.naming.provider.url
→ URL of the LDAP service provider. There is also a separate input field for this property.
java.naming.security.authentication
→ The authentication mechanism for directory connection. Unspecified, the value defaults to "none". Other available values are "simple" or a name representing an implementation of SASL (RFC2222). The "simple" mechanism authenticates the user by providing the username along with a plain-text password. Obviously, with this method it is advisable to use an SSL protected connection for security reasons.
java.naming.security.principal
→ The principal or username used to connect to the external directory. Typically the principal is given in DN format. There is also a separate input field for this property.
java.naming.security.credentials
→ The password associated with the principal. There is also a separate input field for this property.
java.naming.security.protocol
→ The protocol used for the connection.
java.naming.ldap.attributes.binary
→ This property defines that a certain attribute is returned using the binary format. It is required for the proper operation of Ubisecure CustomerID that objectGUID attribute is returned using the binary format.
policy.password.protocol
→ This property defines the password protocol that is used in the authentication methods linked to this service.
com.ubisecure.util.ldap.server.list
→ A whitespace separated list of LDAP servers.
com.ubisecure.util.ldap.failover.type
→ Defines the type of failover connection. In Ubisecure CustomerID this must be single-master. In single-master failover, while opening a new connection, the servers on the com.ubisecure.util.ldap.server.list are accessed in order from first to last. The first established connection is kept until there is a need to make a switch in a failover situation.

Ubisecure supports also other options related to LDAP client-side failover with replicated directories. Please refer to pages Installation - SSO and Upgrade - SSO for further instructions about enabling client-side failover.

eidm2.properties

There are some properties in the eidm2.properties file that are either crucial or extremely relevant for Active Directory integration. They are:

main.ldap.directory = ad
login.generation = random
login.attribute = sAMAccountName 
group.samaccountname.generation = random

The values don't necessarily need to be the same as in the example above, but those values provide a reasonable starting point for further configuration.

Browser not supported