LDAP Login

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.

Introductory notes:

  • 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 objectClass=posixAccount attribute set.
  • Should have a uid attribute. 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 like uidNumber and 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 /etc/nsswitch.conf has 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

The RUN statement is a single line and should not be broken up. You may change the FROM line 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 following to 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 (--use-login, --certfile or --autocert) will need to be given when starting the container to enable secure login. Please refer to the Skopos command line documentation for details.