nfrastack/container-lemonldap

About

This repository will build a container for LemonLDAP::NG, an authorization and access manager supporting multiple protocols and standard (SAML, OpenID Connect, CAS) served by Nginx.

• Sane defaults to have a working solution by just running the image
• Automatically generates configuration files on startup, or option to use your own
• Option to just use image as a Handler for external servers
• Handler Option to use file base socket or listen on TCP
• Fail2ban Included for blocking brute force attacks.
• Ready to work out the box for SAML, OpenID, 2FA/2OTP
• Additional modules compiled for Redis, Mysql, Postgres, LDAP Session/Config Storage
• Choice of Logging (Console, File, Syslog)

Maintainer

• Nfrastack

Table of Contents

• About
• Maintainer
• Table of Contents
• Installation
  • Prebuilt Images
  • Quick Start
  • Persistent Storage
• Configuration
  • Environment Variables
    • Base Images used
    • Core Variables
    • Configuration Variables
    • Socket & Networking Variables
    • Logging Variables
    • Handler Variables
    • Manager Variables
    • Manager API Variables
    • Portal Variables
    • Test Site Variables
    • Session Backends
  • Users and Groups
  • Networking
• Maintenance
  • Shell Access
• Support & Maintenance
• References
• License

Prerequisites and Assumptions

• Assumes you are using some sort of SSL terminating reverse proxy such as:
  • Traefik
  • Nginx
  • Caddy
• You must have access to create records on your DNS server to be able to setup the demo installation before configuration.

Installation

Prebuilt Images

Feature limited builds of the image are available on the Github Container Registry and Docker Hub.

To unlock advanced features, one must provide a code to be able to change specific environment variables from defaults. Support the development to gain access to a code.

To get access to the image use your container orchestrator to pull from the following locations:

ghcr.io/nfrastack/container-lemonldap:(image_tag)
docker.io/nfrastack/lemonldap:(image_tag)

Image tag syntax is:

<image>:<optional tag>

Example:

ghcr.io/nfrastack/container-lemonldap:latest or

ghcr.io/nfrastack/container-lemonldap:1.0 or

• latest will be the most recent commit
• An optional tag may exist that matches the CHANGELOG - These are the safest
• If there are multiple distribution variations it may include a version - see the registry for availability

Have a look at the container registries and see what tags are available.

Multi-Architecture Support

Images are built for amd64 by default, with optional support for arm64 and other architectures.

Quick Start

• The quickest way to get started is using docker-compose. See the examples folder for a working compose.yml that can be modified for your use.

• Map persistent storage for access to configuration and data files for backup.

• Set various environment variables to understand the capabilities of this image.

Persistent Storage

The following directories are used for configuration and can be mapped for persistent storage.

Configuration

Environment Variables

Base Images used

This image relies on a customized base image in order to work. Be sure to view the following repositories to understand all the customizable options:

Below is the complete list of available options that can be used to customize your installation.

• Variables showing an 'x' under the Advanced column can only be set if the containers advanced functionality is enabled.

There are a huge amount of configuration variables and it is recommended that you get comfortable for a few hours with the LemonLDAP::NG Documentation

You will eventually based on your usage case switch over to SETUP_TYPE=MANUAL and edit your own lemonldap-ng.ini/instance.cfg. While I've tried to make this as easy to use as possible, once in production you'll find much better success with large implementations with this approach.

By Default this image is ready to run out of the box, without having to alter any of the settings with the exception of the _HOSTNAME vars. You can also change the majority of these settings from within the Manager. There are instances where these variables would want to be set if you are running multiple handlers or need to enforce a Global Setting for one specific installation.

Core Variables

Configuration Variables

Socket & Networking Variables

If API, HANDLER, MANAGER, PORTAL, TEST _SOCKET not set these values will be used. If you wish to override use the appropriate variables with the values of either unix://path.sock or ip:port

Logging Variables

Instance Settings

These options affect both HANDLER and PORTAL configuration. If you wish to override them specifically then use the specific HANDLER_SESSIONS.. or PORTAL_SESSIONS.. overrides

Handler Variables

For usage with MODE=HANDLER

Manager Variables

For usage with MODE=MANAGER

Manager API Variables

For usage with MODE=API

Portal Variables

For usage with MODE=PORTAL

With impersonation, if you enable it, it will add a new field to your login screen, which may not be what you want if this is a production system. You will need to create two custom themes (one as a replica of bootstrap, and one for impersonation). In the custom theme, make modifications to login.tpl to stop it from loading impersonation.tpl, yet in your impersonation theme, leave it in there. Then, when one of your admin/support team visits the custom IMPERSONATE_HOSTNAME you have defined it will load the full theme with allows to impersonate, where as the default theme will not show this.

When changing the path of PORTAL_ APPS ICONS LOGOS LANGUAGES path if the destination path is empty it will make a copy of the original vendor supplied content in your folder. There is an additional file .source which will detail the version of LemonLDAP:NG and the date that the content was copied. It is important that you watch the vendor supplied folders in later images to ensure that you are being kept up to date with the appropriate assets.

If wishing to use Fail2Ban to lock out problematic hosts - you must enable CONTAINER_ENABLE_FIREWALL=TRUE AND CONTAINER_ENABLE_FAIL2BAN=TRUE

Test Site Variables

For usage with MODE=TEST

Session Backends

The *_SESSIONS_ACTIVE_TYPE and *_SESSIONS_PERSISTENT_TYPE variables (INSTANCE_, HANDLER_, and PORTAL_ prefixes) accept the following values:

For DB including redis backends, set the _DB_HOST/_DB_NAME/_DB_USER/_DB_PASS component vars and the DSN is built automatically. A full _DB_DSN override is also accepted for advanced SQL connection strings.

Session Examples

PostgreSQL (PgJSON):

PORTAL_SESSIONS_ACTIVE_TYPE=pgjson
PORTAL_SESSIONS_ACTIVE_DB_HOST=postgres
PORTAL_SESSIONS_ACTIVE_DB_NAME=llng
PORTAL_SESSIONS_ACTIVE_DB_USER=llng
PORTAL_SESSIONS_ACTIVE_DB_PASS_FILE=/run/secrets/db_password
PORTAL_SESSIONS_ACTIVE_DB_TABLE=sessions

MySQL with a non-default port:

PORTAL_SESSIONS_ACTIVE_TYPE=mysqljson
PORTAL_SESSIONS_ACTIVE_DB_HOST=mysql
PORTAL_SESSIONS_ACTIVE_DB_PORT=3307
PORTAL_SESSIONS_ACTIVE_DB_NAME=llng
PORTAL_SESSIONS_ACTIVE_DB_USER=llng
PORTAL_SESSIONS_ACTIVE_DB_PASS_FILE=/run/secrets/db_password
PORTAL_SESSIONS_ACTIVE_DB_INDEX=_session_id,_utime

SQLite (no host, user, or password needed):

PORTAL_SESSIONS_ACTIVE_TYPE=sqlite
PORTAL_SESSIONS_ACTIVE_DB_NAME=/data/sessions/active.db

Redis (_DB_NAME is the Redis database number):

PORTAL_SESSIONS_ACTIVE_TYPE=redis
PORTAL_SESSIONS_ACTIVE_DB_HOST=redis
PORTAL_SESSIONS_ACTIVE_DB_PORT=6379
PORTAL_SESSIONS_ACTIVE_DB_NAME=0
PORTAL_SESSIONS_ACTIVE_DB_PASS_FILE=/run/secrets/redis_pass

Redis via UNIX socket (Redis-specific):

PORTAL_SESSIONS_ACTIVE_TYPE=redis
PORTAL_SESSIONS_ACTIVE_REDIS_SOCK=/run/redis/redis.sock
PORTAL_SESSIONS_ACTIVE_DB_PASS_FILE=/run/secrets/redis_pass

Or with a manually specified DSN for advanced SQL connection options:

PORTAL_SESSIONS_ACTIVE_TYPE=pgjson
PORTAL_SESSIONS_ACTIVE_DB_DSN=dbi:Pg:dbname=llng;host=postgres-db;port=5432;sslmode=require
PORTAL_SESSIONS_ACTIVE_DB_USER=llng
PORTAL_SESSIONS_ACTIVE_DB_PASS_FILE=/run/secrets/db_password

For LDAP:

PORTAL_SESSIONS_ACTIVE_TYPE=LDAP
PORTAL_SESSIONS_ACTIVE_LDAP_SERVER=ldap://openldap-app:389
PORTAL_SESSIONS_ACTIVE_LDAP_BASE=ou=sessions,dc=example,dc=com
PORTAL_SESSIONS_ACTIVE_LDAP_BIND_DN=cn=llng,dc=example,dc=com
PORTAL_SESSIONS_ACTIVE_LDAP_BIND_PASS_FILE=/run/secrets/ldap_password

The same _DB_*, _REDIS_*, and _LDAP_* sub-variables apply to INSTANCE_SESSIONS_*, HANDLER_SESSIONS_*, and PORTAL_SESSIONS_* with their respective prefixes.

Users and Groups

Networking

Maintenance

Shell Access

For debugging and maintenance, bash and sh are available in the container.

Support & Maintenance

• For community help, tips, and community discussions, visit the Discussions board.
• For personalized support or a support agreement, see Nfrastack Support.
• To report bugs, submit a Bug Report. Usage questions will be closed as not-a-bug.
• Feature requests are welcome, but not guaranteed. For prioritized development, consider a support agreement.
• Updates are best-effort, with priority given to active production use and support agreements.

References

• https://lemonldap-ng.org

License

This project is licensed under the MIT License - see the LICENSE file for details.