Configuring StartTLS with an external LDAP server

StartTLS is an extension that uses TLS/SSL to secure an insecure LDAP connection. StartTLS retains the current connection on the same port (389) while it encrypts the data. The security provision can be turned on and off according to the requirements.

For more information on StartTLS, see Lightweight Directory Access Protocol.

To use this feature, apply the 3962 WUM update for WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM).

To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide.

Before you begin

Make sure you have an LDAP server such as OpenLDAP or Active Directory that is up and running.

Click here for further information

If you do not have an LDAP server installed, follow the instructions in Installing LDAP in Linux or Installing LDAP in Windows to install it in order to use StartTLS support.
Enable StartTLS on OpenLDAP Server.

You might need to configure other types of LDAP servers, e.g., AD LDAP server, based on the guidelines given specifically for them.
1. Obtain a CA-signed certificate for your LDAP server.
2. To provide root permission to those certificates, copy them to the /etc/ldap/sasl2/ repository.
3. Create a file with the following content and save it with the .ldif extension. Now you need to replace the corresponding certificate file names.
```
# create new
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ldap/sasl2/ca-certificates.crt
-
replace: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ldap/sasl2/server.crt
-
replace: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ldap/sasl2/server.key
```
4. Execute the following command to apply the changes to your OpenLDAP system.
```
ldapmodify -Y EXTERNAL -H ldapi:/// -f <filename>.ldif
```
5. Restart the LDAP server.
```
systemctl restart slapd
```

Configuring WSO2 Identity Server

Execute the following command in a command prompt to import the LDAP server’s public certificate to the WSO2 client keystore.

keytool -importcert -file <certificate file> -keystore <IS_HOME>/repository/resources/security/client-truststore.jks -alias <your alias>

If you are configuring a primary userstore, add the following property to the corresponding user store configuration in the user-mgt.xml file located in <IS_HOME>/repository/conf. If you are configuring a secondary userstore, add this to the corresponding user store configuration in the XML file.
```
<Property name="StartTLSEnabled">true</Property>
```
Run WSO2 Identity Server.

Verifying the functionality of StartTLS

To enable the debug log, uncomment the following property in the log4j.properties file in the <IS_HOME>/repository/conf/ folder.

log4j.logger.org.wso2.carbon.user.core=DEBUG

Debug logs allow users to view connection establishments and the termination of StartTLS as follows.

[2019-02-11 16:24:18,143] DEBUG {org.wso2.carbon.user.core.ldap.LdapContextWrapper} -  StartTLS connection established successfully with LDAP server
[2019-02-11 16:24:18,144] DEBUG {org.wso2.carbon.user.core.ldap.LdapContextWrapper} -  Attribute java.naming.security.authentication is added to the TLS LdapContext environment
[2019-02-11 16:24:18,145] DEBUG {org.wso2.carbon.user.core.ldap.LdapContextWrapper} -  Attribute java.naming.security.principal is added to the TLS LdapContext environment
[2019-02-11 16:24:18,145] DEBUG {org.wso2.carbon.user.core.ldap.LdapContextWrapper} -  Attribute java.naming.security.credentials is added to the TLS LdapContext environment
[2019-02-11 16:24:18,148] DEBUG {org.wso2.carbon.user.core.ldap.StartTlsResponseWrapper} -  Closing the StartTLS connection with LDAP server

You can also use network-sniffing tools (like wireshark) to analyze the encrypted packets.