58 OpenLDAP

LDAP is probably the most ubiquitous authentication backend, before the current era of “stupid social sign-ons”. Many of the recipes featured in the cookbook (NextCloud, Kanboard, Gitlab, etc) offer LDAP integration.

58.1 Big deal, who cares?

If you’re the only user of your tools, it probably doesn’t bother you too much to setup new user accounts for every tool. As soon as you start sharing tools with collaborators (think 10 staff using NextCloud), you suddenly feel the pain of managing a growing collection of local user accounts per-service.

Enter OpenLDAP - the most crusty, PITA, fiddly platform to setup (yes, I’m a little bitter, dynamic configuration backend!), but hugely useful for one job - a Lightweight Protocol for managing a Directory used for Access (see what I did there?)

The nice thing about OpenLDAP is, like MySQL, once you’ve setup the server, you probably never have to interact directly with it. There are many tools which will let you interact with your LDAP database via a(n ugly) UI.

This recipe combines the raw power of OpenLDAP with the flexibility and featureset of LDAP Account Manager.

58.2 What’s the takeaway?

What you’ll end up with is a directory structure which will allow integration with popular tools (NextCloud, Kanboard, Gitlab, etc), as well as with KeyCloak (an upcoming recipe), for true SSO.

58.3 Ingredients

Docker swarm cluster with persistent shared storage
Traefik configured per design
DNS entry for the hostname (i.e. “lam.your-domain.com”) you intend to use for LDAP Account Manager, pointed to your keepalived IP

58.4 Preparation

Setup data locations

We’ll need several directories to bind-mount into our container, so create them in /var/data/openldap:

mkdir /var/data/openldap/openldap
mkdir /var/data/runtime/openldap/

data layout explanation

Prepare environment

Create /var/data/openldap/openldap.env, and populate with the following variables, customized for your own domain structure. Take care with LDAP_DOMAIN, this is core to your directory structure, and can’t easily be changed later.

LDAP_DOMAIN=batcave.gotham
LDAP_ORGANISATION=BatCave Inc
LDAP_ADMIN_PASSWORD=supermansucks
LDAP_TLS=false

# Use these if you plan to protect the LDAP Account Manager webUI with an oau\
th_proxy
OAUTH2_PROXY_CLIENT_ID=
OAUTH2_PROXY_CLIENT_SECRET=
OAUTH2_PROXY_COOKIE_SECRET=

OAuth proxy

Create authenticated-emails.txt, and populate with the email addresses (matched to GitHub user accounts, in my case) to which you want grant access, using OAuth2.

Create config.cfg

The Dockerized version of LDAP Account Manager is a little fiddly. In order to maintain a config file which persists across container restarts, we need to present the container with a copy of /var/www/html/config/lam.conf, tweaked for our own requirements.

Create /var/data/openldap/lam/config/config.cfg as follows:

???+ note “Much scroll, very text. Click here to collapse it for better readability”

    # password to add/delete/rename configuration profiles (default: lam)
    password: {SSHA}D6AaX93kPmck9wAxNlq3GF93S7A= R7gkjQ==

    # default profile, without ".conf"
    default: batcave

    # log level
    logLevel: 4

    # log destination
    logDestination: SYSLOG

    # session timeout in minutes
    sessionTimeout: 30

    # list of hosts which may access LAM
    allowedHosts:

    # list of hosts which may access LAM Pro self service
    allowedHostsSelfService:

    # encrypt session data
    encryptSession: true

    # Password: minimum password length
    passwordMinLength: 0

    # Password: minimum uppercase characters
    passwordMinUpper: 0

    # Password: minimum lowercase characters
    passwordMinLower: 0

    # Password: minimum numeric characters
    passwordMinNumeric: 0

    # Password: minimum symbolic characters
    passwordMinSymbol: 0

    # Password: minimum character classes (0-4)
    passwordMinClasses: 0

    # Password: checked rules
    checkedRulesCount: -1

    # Password: must not contain part of user name
    passwordMustNotContain3Chars: false

    # Password: must not contain user name
    passwordMustNotContainUser: false

    # Email format (default/unix)
    mailEOL: default

    # PHP error reporting (default/system)
    errorReporting: default

    # License
    license:

Create <profile>.cfg

While config.cfg (above) defines application-level configuration, <profile>.cfg is used to configure “domain-specific” configuration. You probably only need a single profile, but LAM could theoretically be used to administer several totally unrelated LDAP servers, ergo the concept of “profiles”.

Create yours profile (you chose a default profile in config.cfg above, remember?) by creating /var/data/openldap/lam/config/<profile>.conf, as follows:

???+ note “Much scroll, very text. Click here to collapse it for better readability”

    # LDAP Account Manager configuration
    #
    # Please do not modify this file manually. The configuration can be done \
completely by the LAM GUI.
    #
    #########################################################################\
##########################

    # server address (e.g. ldap://localhost:389 or ldaps://localhost:636)
    ServerURL: ldap://openldap:389

    # list of users who are allowed to use LDAP Account Manager
    # names have to be separated by semicolons
    # e.g. admins: cn=admin,dc=yourdomain,dc=org;cn=root,dc=yourdomain,dc=org
    Admins: cn=admin,dc=batcave,dc=gotham

    # password to change these preferences via webfrontend (default: lam)
    Passwd: {SSHA}h39N9+gg/Qf1K/986VkKrjWlkcI= S/IAUQ==

    # suffix of tree view
    # e.g. dc=yourdomain,dc=org
    treesuffix: dc=batcave,dc=gotham

    # default language (a line from config/language)
    defaultLanguage: en_GB.utf8

    # Path to external Script
    scriptPath:

    # Server of external Script
    scriptServer:

    # Access rights for home directories
    scriptRights: 750

    # Number of minutes LAM caches LDAP searches.
    cachetimeout: 5

    # LDAP search limit.
    searchLimit: 0

    # Module settings

    modules: posixAccount_user_minUID: 10000
    modules: posixAccount_user_maxUID: 30000
    modules: posixAccount_host_minMachine: 50000
    modules: posixAccount_host_maxMachine: 60000
    modules: posixGroup_group_minGID: 10000
    modules: posixGroup_group_maxGID: 20000
    modules: posixGroup_pwdHash: SSHA
    modules: posixAccount_pwdHash: SSHA

    # List of active account types.
    activeTypes: user,group


    types: suffix_user: ou=People,dc=batcave,dc=gotham
    types: attr_user: #uid;#givenName;#sn;#uidNumber;#gidNumber
    types: modules_user: inetOrgPerson,posixAccount,shadowAccount

    types: suffix_group: ou=Groups,dc=batcave,dc=gotham
    types: attr_group: #cn;#gidNumber;#memberUID;#description
    types: modules_group: posixGroup

    # Password mail subject
    lamProMailSubject: Your password was reset

    # Password mail text
    lamProMailText: Dear @@givenName@@ @@sn@@,+::++::+your password was reset\
 to: @@newPassword@@+::++::++::+Best regards+::++::+deskside support+::+

    serverDisplayName:


    # enable TLS encryption
    useTLS: no


    # follow referrals
    followReferrals: false


    # paged results
    pagedResults: false

    referentialIntegrityOverlay: false


    # time zone
    timeZone: Europe/London

    scriptUserName:

    scriptSSHKey:

    scriptSSHKeyPassword:


    # Access level for this profile.
    accessLevel: 100


    # Login method.
    loginMethod: list


    # Search suffix for LAM login.
    loginSearchSuffix: dc=batcave,dc=gotham


    # Search filter for LAM login.
    loginSearchFilter: uid=%USER%


    # Bind DN for login search.
    loginSearchDN:


    # Bind password for login search.
    loginSearchPassword:


    # HTTP authentication for LAM login.
    httpAuthentication: false


    # Password mail from
    lamProMailFrom:


    # Password mail reply-to
    lamProMailReplyTo:


    # Password mail is HTML
    lamProMailIsHTML: false


    # Allow alternate address
    lamProMailAllowAlternateAddress: true

    jobsBindPassword:

    jobsBindUser:

    jobsDatabase:

    jobsDBHost:

    jobsDBPort:

    jobsDBUser:

    jobsDBPassword:

    jobsDBName:

    jobToken: 190339140545

    pwdResetAllowSpecificPassword: true

    pwdResetAllowScreenPassword: true

    pwdResetForcePasswordChange: true

    pwdResetDefaultPasswordOutput: 2

    twoFactorAuthentication: none

    twoFactorAuthenticationURL: https://localhost

    twoFactorAuthenticationInsecure:

    twoFactorAuthenticationLabel:

    twoFactorAuthenticationOptional:

    twoFactorAuthenticationCaption:
    tools: tool_hide_toolOUEditor: false
    tools: tool_hide_toolProfileEditor: false
    tools: tool_hide_toolSchemaBrowser: false
    tools: tool_hide_toolServerInformation: false
    tools: tool_hide_toolTests: false
    tools: tool_hide_toolPDFEditor: false
    tools: tool_hide_toolFileUpload: false
    tools: tool_hide_toolMultiEdit: false

Setup Docker Swarm

Create a docker swarm config file in docker-compose syntax (v3), something like this, at (/var/data/config/openldap/openldap.yml)

with my patreon patronspremixgit pulldocker stack deploy

version: '3'

services:
  openldap:
    image: osixia/openldap
    env_file: /var/data/config/openldap/openldap.env
    networks:
    - traefik_public
    - auth_internal
    volumes:
    - /var/data/runtime/openldap/:/var/lib/ldap
    - /var/data/openldap/openldap/:/etc/ldap/slapd.d

  lam:
    image: jacksgt/ldap-account-manager
    networks:
    - auth_internal
    volumes:
    - /var/data/openldap/lam/config/config.cfg:/var/www/html/config/config.cfg
    - /var/data/openldap/lam/config/batcave.conf:/var/www/html/config/batcave\
.conf

  lam-proxy:
    image: funkypenguin/oauth2_proxy
    env_file: /var/data/config/openldap/openldap.env
    networks:
      - traefik_public
      - auth_internal
    deploy:
      labels:
        - traefik.frontend.rule=Host:lam.batcave.com
        - traefik.docker.network=traefik_public
        - traefik.port=4180
    command: |
      -cookie-secure=false
      -upstream=http://lam:8080
      -redirect-url=https://lam.batcave.com
      -http-address=http://0.0.0.0:4180
      -email-domain=batcave.com
      -provider=github


networks:
  # Used to expose lam-proxy to external access, and openldap to keycloak
  traefik_public:
    external: true

  # Used to expose openldap to other apps which want to talk to LDAP, includi\
ng LAM
  auth_internal:
    external: true

Normallymy list

anotherauth_internal, see below

Create another stack config file (/var/data/config/openldap/auth.yml) containing just the auth_internal network, and a dummy container:

version: "3.2"

# What is this?
#
# This stack exists solely to deploy the auth_internal overlay network, so th\
at
# other stacks (including keycloak and openldap) can attach to it

services:
  scratch:
    image: scratch
    deploy:
      replicas: 0
    networks:
      - internal

networks:
  internal:
    driver: overlay
    attachable: true
    ipam:
      config:
        - subnet: 172.16.39.0/24

58.5 Serving

Launch OpenLDAP stack

Create the auth_internal overlay network, by running docker stack deploy auth -c /var/data/config/openldap/auth.yml, then launch the OpenLDAP stack by running docker stack deploy openldap -c /var/data/config/openldap/openldap.yml

Log into your new LAM instance at https://YOUR-FQDN.

On first login, you’ll be prompted to create the “ou=People” and “ou=Group” elements. Proceed to create these.

You’ve now setup your OpenLDAP directory structure, and your administration interface, and hopefully won’t have to interact with the “special” LDAP Account Manager interface much again!

Create your users using the “New User” button.

The Common Observatory

58.6 Chef’s Notes

The KeyCloak recipe illustrates how to integrate KeyCloak with your LDAP directory, giving you a cleaner interface to manage users, and a raft of SSO / OAuth features.

hero: Docker-mailserver - A recipe for a self-contained mailserver and friends

Up next

59 Mail Server