This document describes a basic procedure for building a new Docker image, based on a Skopos image, which includes support for authenticating with LDAP using PAM.
- This procedure applies to Skopos releases whose images are based on Ubuntu (e.g.
opsani/skopos:edge). Skopos images based on Alpine Linux use a different package manager (apk) and require different commands to install the PAM modules needed to authenticate with LDAP. The procedure for Alpine is under development and will be published later on this page.
- This procedure produces a new Docker container image, based on the original Skopos image, with added configuration for LDAP authentication.
- This document is not intended as a comprehensive manual on configuring the PAM LDAP module or your LDAP server. If the example settings provided here do not match your LDAP configuration, please refer to the documentation that comes with the Ubuntu libpam-ldap package and the LDAP server that you plan to use. If you do not control the latter, you may need the help of the server’s administrator.
LDAP Server Requirements
The setup documented here uses the Linux PAM module in a very basic configuration for LDAP to perform authentication. This module has certain default expectations as to the contents of the user database in LDAP. In some cases when these are not satisfied, advanced configuration settings might still allow the use of the PAM module with your LDAP server, but the full variety of possible settings is extensive and is outside the scope of this document.
The LDAP users’ database entries:
- Should have the
- Should have a
uidattribute. This will be used as the login name when logging in to Skopos.
If it is a requirement to restrict login to a particular group of users, the database should contain a
group entry with a multi-valued attribute
containing a list of the user IDs (matching the
uid attribute in the user’s entry) that are members of that group.
The following is a typical user record (in LDIF text form)
sufficient for use with PAM LDAP (note it includes some attributes
gidNumber that aren’t actually used when
Skopos authenticates the user, but may be required if the same user
entry is used for a Linux shell login):
dn: uid=johndoe,ou=People,dc=ec2,dc=internal objectClass: person objectClass: posixAccount objectClass: shadowAccount uid: johndoe cn: John Doe sn: Doe loginShell: /bin/bash uidNumber: 9999 gidNumber: 9999 homeDirectory: / description: This is an example user userPassword:: (base64 hashed passwd) =
The following is an example group record (with two users in it) that is
sufficient for use with the
pam_groupdn setting shown in
the example configuration further below (this is also a valid group
record for the libnss-ldap library and allows it to be used when
group: ldap configured to allow
lookup of Linux groups in the LDAP database):
dn: cn=skopos,ou=Group,dc=ec2,dc=internal cn: skopos objectClass: posixGroup gidNumber: 5001 memberUid: johndoe memberUid: mj
Skopos Image Preparation
On a host that has access to the Docker command-line client,
create an empty directory, and create a file named
Dockerfile in this directory with the following contents:
FROM opsani/skopos:edge COPY ldap.* /etc/ RUN apt-get update ; printf 'Name: ldap-auth-config/move-to-debconf\nTemplate: ldap-auth-config/move-to-debconf\nValue: true\nOwners: ldap-auth-config\nFlags: seen\nVariables:\n newfn = /etc/ldap.conf\n nssfn = /etc/libnss-ldap.conf\n pamfn = /etc/pam-ldap.conf\n' | DEBIAN_FRONTEND=noninteractive DEBCONF_DB_FALLBACK=Pipe apt-get -y --no-install-recommends install ldap-auth-config && apt-get -y --no-install-recommends install libpam-ldap libnss-ldap
RUNstatement is a single line and should not be broken up. You may change the
FROMline as needed, but this Skopos image must be based on Ubuntu.
In the same directory, place a file named
ldap.conf with the
settings needed for your LDAP server, including at least the first
4 entries shown in the following example:
base dc=ec2,dc=internal ldap_version 3 pam_password md5 uri ldap://ip-10-0-0-7.ec2.internal/ # optional: add binddn/bindpw if something other than Skopos will run in the # same container (as a non-root user) AND your server does not accept # anonymous bind binddn cn=Mojo Jojo,ou=People,dc=ec2,dc=internal bindpw admin389 # optional: add rootbinddn if your LDAP server does not accept anonymous binds rootbinddn cn=Directory Manager # optional: restrict login to a specific group pam_groupdn cn=skopos,ou=Group,dc=ec2,dc=internal pam_member_attribute memberUid
If you’ve set
rootbinddn, also create a separate file with the bind password, named
ldap.secret and set it to be readable only to the user (
chmod go-rwx ldap.secret).
If your LDAP server uses a secure connection, also add the
ldap.conf AND include the necessary file/directory
with the SSL certificate in the container build:
ssl start_tls # either: tls_cacertdir /cert # or: tls_cacertfile /cert/ldap-ca-verify-cert.pem
The cert file or directory needs to be included in the Dockerfile, e.g., like this:
COPY ldap-ca-verify-cert.pem /cert/
To review additional possible settings in
ldap.conf, install the
libpam-ldap package on a Ubuntu OS and run
man pam_ldap. If you have the Docker command-line client at hand, the following command can be used to view the pam_ldap man page:
docker run --rm -ti ubuntu:16.04 sh -c 'apt-get update ; DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y libpam-ldap man-db ; man pam_ldap'
Example settings can also be found in /usr/share/ldap-auth-config/ldap.conf (installed by the ldap-auth-config package).
Once all needed files are in place, run the following command to build the new Skopos image with PAM LDAP support:
docker build -t opsani/skopos:ldap .
Note: the current directory for this command should be the one which includes the Dockerfile and other required files that it refers to. You can change the image tag as desired.
The new image can now be used to launch Skopos. Note that
additional command-line parameters (
--autocert) will need to be given when starting the container to
enable secure login. Please refer to the Skopos command line
documentation for details.