151 lines
7.2 KiB
Markdown
151 lines
7.2 KiB
Markdown
---
|
|
title: "How to lean an XWiki Docker container against Active Directory over LDAPS ?"
|
|
date: 2018-11-21
|
|
url: how-to-lean-an-xwiki-docker-container-against-active-directory-over-ldaps
|
|
layout: post
|
|
category: Tutorials
|
|
image: /img/blog/how-to-lean-an-xwiki-docker-container-against-active-directory-over-ldaps.png
|
|
description: "A complete guide to connect an XWiki Docker container to an Active Directory over LDAPS"
|
|
---
|
|
|
|
[](/img/blog/how-to-lean-an-xwiki-docker-container-against-active-directory-over-ldaps.png)
|
|
|
|
### Introduction
|
|
|
|
Today we will treat a very specific stack and associated needs :
|
|
|
|
* [XWiki](https://www.xwiki.com/) (Docker-ised with the [official image](https://hub.docker.com/_/xwiki/))
|
|
|
|
* Active Directory for LDAP users directory
|
|
|
|
* LDAP**S** for the XWiki <-> Active Directory connection
|
|
|
|
> In this guide I assume that the certificate served by your Active Directory for LDAP**S** connections has been signed by a third certificate authority ([documentation](https://social.technet.microsoft.com/wiki/contents/articles/2980.ldap-over-ssl-ldaps-certificate.aspx)).
|
|
|
|
To enable the LDAP authentication process within XWiki, we will be using the [recommended LDAP authenticator extension](https://extensions.xwiki.org/xwiki/bin/view/Extension/LDAP/Authenticator/), as the [Active Directory application](https://store.xwiki.com/xwiki/bin/view/Extension/ActiveDirectoryApplication) 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`
|
|
|
|
{% highlight bash %}
|
|
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
|
|
{% endhighlight %}
|
|
|
|
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`
|
|
|
|
{% highlight configuration %}
|
|
#-# 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
|
|
{% endhighlight %}
|
|
|
|
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 :
|
|
|
|
{% highlight text %}
|
|
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
|
|
{% endhighlight %}
|
|
|
|
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](https://github.com/xwiki-contrib/docker-xwiki) (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 LDAP**S** 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
|
|
|
|
* [XWiki's LDAPS patch](https://jira.xwiki.org/browse/XWIKI-865)
|
|
|
|
* [XWiki's LDAP module official documentation](https://extensions.xwiki.org/xwiki/bin/view/Extension/LDAP/Authenticator/UseCases/#HUseLDAPoverSSL28ldapsauthentication29)
|
|
|
|
* Hours of testing and debugging
|