A missing blog post image

Introduction

Today we will treat a very specific stack and associated needs :

  • XWiki (Docker-ised with the official image)

  • Active Directory for LDAP users directory

  • LDAPS for the XWiki <-> Active Directory connection

In this guide I assume that the certificate served by your Active Directory for LDAPS connections has been signed by a third certificate authority (documentation).

To enable the LDAP authentication process within XWiki, we will be using the recommended LDAP authenticator extension, as the Active Directory application is unfortunately not free of charge.

The procedure

First, we will review a little BASH script achieving most of the work for this specific use case :

# nano run_xwiki.sh

docker run \
        --name xwiki \
        -p 127.0.0.1:8080:8080 \
        -v /data/xwiki:/usr/local/xwiki \
        -v /usr/local/share/ca-certificates/your-ca.crt:/usr/local/share/ca-certificates/your-ca.crt:ro \
        -e DB_USER=xwiki \
        -e DB_PASSWORD=pass_4_xwiki \
        -e DB_DATABASE=xwiki \
        -e DB_HOST=127.0.0.1 \
        --restart=always \
        -d xwiki:mysql-tomcat

docker exec -it xwiki update-ca-certificates
docker exec -it xwiki keytool -import -trustcacerts -alias ca -file /usr/local/share/ca-certificates/your-ca.crt -keystore cacerts

docker restart xwiki

So basically, we create a new container named xwiki from the xwiki:mysql-tomcat official image.
The most important parts are the mounted volumes.
The first one will allow us to tweak the XWiki configuration from our host (and of course will add some persistence for the data files and the extensions), under /data/xwiki/.
The second one is interesting : We actually map the bundle of our CA (present on the host) into the /usr/local/share/ca-certificates/ directory, which is supposed to store our personal CAs (note the ro (read only) aspect of the mapping).
After its creation, we execute two commands within our container :

  1. We synchronize the container CA bundles to consider our new added CA

  2. We use keytool to add our CA to the JVM’s default keystore

Note : We tried each one of the above procedures separately ; It didn’t work out.

Once the additions has been performed, we restart our container to make the JVM reloading the known certificate authorities list.

Don’t forget to change the database configuration (or the base image if you don’t use MySQL) to fit with your setup !

The configuration

Now that you noticed where our XWiki configuration is located, I will show you the required entries to perform LDAP authentication from the application !

# nano /data/xwiki/data/xwiki.cfg

#-# LDAP authentication service
xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl

#-# Turn LDAP authentication on
xwiki.authentication.ldap=1

#-# Enable local accounts in addition to LDAP
xwiki.authentication.ldap.trylocal=1

#-# Active Directory connection & Fields mapping
xwiki.authentication.ldap.server=YOUR.SIGNED.AD.FQDN
xwiki.authentication.ldap.port=636
xwiki.authentication.ldap.ssl=1
xwiki.authentication.ldap.UID_attr=sAMAccountName
xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,email=mail,ldap_dn=dn
xwiki.authentication.ldap.update_user=1

#-# LDAP research
xwiki.authentication.ldap.bind_DN=CN=PriviligedUser,DC=YOUR,DC=DOMAIN,DC=NAME
xwiki.authentication.ldap.bind_pass=PriviligedUserPassword
xwiki.authentication.ldap.base_DN=OU=Users,DC=YOUR,DC=DOMAIN,DC=NAME

So here we enabled SSL/TLS for LDAP connections and configured some parameters to lean the authentication process against our Active Directory directly.
A precision though : You will have to replace the PrivilegedUser & its associated password by the credentials of an user with read rights on your dictionary.

The execution

Once you think everything is OK on your own, you may run the previous script :

root@host:~# bash run_xwiki.sh
d9f51096aed5df650f09431d87be7203734d5c7f3f22db7854923f69fd491645
Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...

Adding debian:your-ca.pem
done.
done.
Enter keystore password:
Re-enter new password:
*certificate already exists in system-wide CA keystore under alias <debian:your-ca.pem>
Do you still want to add it to your own keystore? [no]: yes
certificate was added to keystore
xwiki

For verification purposes, you should be able to check that :

  1. The container has been correctly created and started (d9f51096aed5df650f09431d87be7203734d5c7f3f22db7854923f69fd491645 in our case)

  2. Your third CA has been added to the trusted container’s CAs (1 added, 0 removed; done.)

  3. Your third CA has been also added to the JVM default keystore (certificate was added to keystore)

  4. The container has been marked to restart (xwiki)

Conclusion

As a “workaround”, we could also fetch and build the Docker image from source (cc @Xysto), but we opted out for a more straightforward way to achieve this.
About updating (if you were wondering), you actually only have to pull the latest version from the Hub (# docker pull xwiki:mysql-tomcat), remove your current running container and execute one more time the run_xwiki.sh script.

To conclude the conclusion, sometimes it could be pretty frightening to browse forums and tutorials about Active Directory and remote third services integration over LDAP ‘cause most of people don’t bother encrypting those connections.
It just means that usually some privileged user credentials move back and forth insecurely over the network.

Friendly reminder : Enabling LDAPS without certificate verification is just useless as a clear-text LDAP connection.
So please, don’t disable it on production servers with real credentials (actually, it looks like you can’t with XWiki, but you may with other services…).

Sources