Connectors

LDAP and Active Directory

A common source for employee and user data is the network directory which is typically LDAP-compliant such as Microsoft's Active Directory. The Connectors support accessing data from these LDAP data sources much like the database Connectors described in previous topics. Typically, the integrator implementing an LDAP or LDAP AD Connector must meet with the LDAP support group to determine the connection string and field names for the data fields to load in to Archibus. 

Currently the LDAP and LDAP AD Connector type supports only importing data from LDAP to Archibus. While there may be reasonable requirements to export data to LDAP, it is not a highly likely scenario for the Connectors. By default, the LDAP Connectors recursively search the directory from the location specified in the Connection String. 

Like database Connectors, LDAP Connectors can take a restriction clause to filter the results returned from the LDAP directory. For example, a restriction of sn=*stef* returns only names that contain the substring stef in the name. Like the examples above, the LDAP Connection String contains all the information required to connect to a particular directory and location.

LDAP://server:389/dc=domain,dc=mycompany,dc=com

LDAP Servers may require a valid username and password to query certain values. If required, provide the username and password information in the Connection Username and Password fields as pictured below.

Note: the password is encrypted when the form is saved.

If you are not familiar with the LDAP structure, you may wish to use the Eclipse IDE's "Apache Directory Studio LDAP Browser" LDAP browser plug-in to create connections and browse the LDAP directory visually.

LDAP over TLS and Certificates

 

Option Description Value

securityAutentication

Optional. Defines the authentication method.  If omitted, the behavior is determined by the service provider (LDAP server).

"none", "simple", "strong" - or SASL

securityProtocol

Optional.  Specifies which security protocol to use when communication is required between the Web Central server and the LDAP Server.  Default is "none" when no value is specified.

Note: while “ssl” is more secure than “none”, it is vulnerable to a known exploit. “tls” is recommended.

"none", "ssl","tls" or "starttls"
keyStorePassPhrase The pass phrase for the java key store to use with installCertificate. Defaults to “changeit”.  

installCertificate

Optional.  In some cases, the LDAP server may require connections to has a valid certificate installed to ensure they are a trusted client.  This setting, when true, will attempt to contact the server and request the certificate.  If the certificate is received, it will be installed in the javaPath setting below.  The certificate must be installed in the Open JDK that is used by Web Central.

"true" or "false"

ldapHost

Optional when installCertificate is "false" otherwise you must specify the ldapHost name.

"YourLdapServerOrRIP"

ldapPort

Optional when installCertificate is "false" otherwise you must specify the ldapPort number.

636 or 389 (typically)

javaPath

Optional when installCertificate is "false" otherwise the certificate will be installed in the Server's working directory.  If direct access to the Web Central server's Open JDK is not available, specify a temporary location and have the system administrator place the certificate file in the Java security folder.

 
referral Defaults to “follow”. See Context (Java Platform SE 8 ) “follow”

Installing LDAP Security Certificates

As described in the table above, some sites may require that a valid certificate be installed in the Web Central server's Open JDK in order to be a trusted client when making authentication requests or queries. Even though access may be granted through LDAP browsers, it is possible that a browser negotiates with the server to trust the certificate or downloads the certificate automatically. Archibus and the Connectors connect to LDAP at a lower level and automatic certificate administration is not supported.

The installCertificate parameters are a convenient method for requesting, downloading. and installing the certificate.  Once a certificate (a file named "jssecacerts" or "cacerts") has been successfully installed in the Open JDK, the installCertificate optional parameters can be disabled or removed from the LDAP Connectors.

When installCertificate is enabled, all the other LDAP parameters must be defined as listed in the table above.

WARNING: This is a convenient, but insecure, method of obtaining the certificate. See the below discussion for an alternative method

Alternative Method

Consult these sources as an alternative method.

  1. Obtain the certificate. Ldapwiki: Obtain a Certificate from Server

  2. Install the certificate. Import the Certificate as a Trusted Certificate (The Java™ Tutorials > Security Features in Java SE > Signing Code and Granting It Permissions)

  3. If needed, start Web Central with a specific key store. Starting the application server with the keystores

If you use this utility, it is your responsibility to ensure the installed certificate is the legitimate certificate for the server:

  1. Extract it from the key store. Export the Public Key Certificate (The Java™ Tutorials > Security Features in Java SE > Signing Code and Granting It Permissions)

  2. View the certificate, for example: keytool -printcert -file Example.cer.

  3. Verify that the certificate should be trusted.