Documentation for LemonLDAP::NG 2.0¶

Presentation¶

• Presentation
• Quick start tutorial

Upgrading¶

• Upgrade notes

Installation¶

• Before you begin
• Installation on Debian/Ubuntu with packages
• Installation on RHEL/CentOS with packages
• Run in LemonLDAP::NG in Docker

Configuration¶

Portal¶

• Presentation
• Portal customization
• Portal menu
• REST/SOAP servers
• Captcha
• Public pages

Authentication, users and password databases¶

Official Backends	Authentication	Users	Password
Active Directory	✔	✔	✔
Apache (Basic, NTLM, OTP, …)	✔
CAS	✔
SQL Databases	✔	✔	✔
Demonstration	✔	✔	✔
Facebook	✔	✔
GitHub [1]	✔
GPG [2]	✔
Kerberos	✔
LDAP	✔	✔	✔
LinkedIn	✔
Null	✔	✔	✔
OpenID Connect	✔	✔
PAM	✔
Proxy LL::NG	✔	✔
Radius	✔
REST	✔	✔	✔
SAML 2.0 / Shibboleth	✔	✔
Slave	✔	✔
SSL	✔
Twitter	✔
WebID	✔	✔
Yubico OTP	Replaced by Yubico OTP Second Factor
Custom modules	✔	✔	✔

Combo Backends	Authentication	Users	Password
Choice by users	✔	✔	✔
Combination of auth schemes	✔	✔	✔ (since 2.0.10)
Multiple backends stack	Replaced by Combination

Obsolete Backends	Authentication	Users	Password
OpenID	✔	✔
Remote LL::NG	✔	✔

Second factor (documentation)	Authentication	Self-registration
TOTP (Google Authenticator,…)	✔	✔
WebAuthn	✔	✔
E-mail Second Factor	✔	[18]
Yubico OTP	✔	✔
External Second Factor (OTP, SMS,…)	✔	[18]
REST Second Factor	✔	[18]
Radius Second Factor [3]	✔
Password as second factor [4]	✔	✔
TOTP-or-U2F	✔	✔
U2F	✔	✔

New in version 2.0.6: See Additional second factors for configuring several multiple REST, external or e-mail based second factors with different parameters

Auth addons	Authentication
Auto Signin	✔

Identity provider¶

Tip

• All identity provider protocols can be used simultaneously
• LemonLDAP::NG can be used as a proxy between those protocols

Protocol	Service Provider	Identity Provider
CAS 1.0 / 2.0 / 3.0	✔	✔
SAML 2.0 / Shibboleth	✔	✔
OpenID Connect	✔	✔
OpenID 2.0 (deprecated)	✔	✔
Get parameters provider (for poor applications)		✔

Options

Issuers timeout: Delay for issuers for submitting their authentication requests

Tip

• To avoid a bad/expired token and lose redirection to the SP protected application after authentication if IdP URLs are served by different load balancers, you can force Issuer tokens to be stored into Global Storage by editing lemonldap-ng.ini in section [portal]:

[portal]
forceGlobalStorageIssuerOTT = 1

Attacks and Protection¶

Tip

To learn or find out more about security, go to Security documentation

Attack	LLNG protection	System Integrator protection
Brute Force	✔	✔
Page Content	✔
CSRF	✔
Deny of Service		✔
Invisible iFrame	✔	✔
Man-in-the-Middle		✔
Software Exploit		✔
SSO by-passing		✔
XSS	✔
IP reputation	✔	✔

Plugins¶

Name	Description
Adaptative authentication	Rules to modulate authentication level
Auto Signin	Sign-in automatically
Brute Force protection	User must wait to log in after some failed login attempts
CDA	Cross Domain Authentication
Check DevOps [5]	Check DevOps handler file
Check HIBP [19]	Check Have I Been Pwned
Check entropy [21]	Check entropy of password
InitializePasswordReset [22]	Initialize Password Reset by mail
Check state	Check state plugin (test page)
Check user [6]	Check access rights, transmitted headers and session attibutes for a specific user and URL
Configuration viewer	Edit WebSSO configuration in Read Only mode
Context switching [7]	Switch context other users
CrowdSec [8]	CrowdSec bouncer
Custom	Write a custom plugin
Decrypt value [9]	Decrypt ciphered values
Display login history	Display Success/Fails logins
Find user [12]	Search for user account
Force authentication	Force authentication to access to Portal
Global logout [10]	Suggest to close all opened sessions at logout
Grant sessions	Rules to apply before allowing a user to open a session
Impersonation [11]	Allow users to use another identity
NewLocationWarning [13]	Send an email when user sign in from a new location
Notifications system	Display a message during log in process
Portal status	Experimental portal status page
Public pages	Enable public pages system
Refresh session API [14]	Plugin that provides an API to refresh a user session
Reset certificate by mail [15]	Allow users to reset their certificate
Reset password by mail	Send a mail to reset its password
Remember auth choice [20]	Remember user last authentication choice
REST services	REST server for Proxy
SOAP services	SOAP server for Proxy
Trusted browser	Remember previous authentications
Upgrade session	This plugin explains to an already authenticated user that a higher authentication level is required to access the URL instead of reject him

Handlers¶

Handlers are software control agents to be installed on your web servers (Nginx, Traefik, Apache, PSGI like Plack based servers or Node.js).

Handler type	Apache	LLNG FastCGI/uWSGI server (Nginx, Traefik or SSOaaS)	Plack servers	Node.js ( express apps or SSOaaS)	Self protected apps	Comment
Main (default handler)	✔	✔	✔	Partial ** [16] **	✔
AuthBasic	✔	✔	✔		✔	Designed for some server-to-server applications
CDA	✔	✔	✔		✔	For Cross Domain Authentication
DevOps (SSOaaS)	✔	✔	✔	✔		Allows application developers to define their own rules and headers inside their applications
DevOpsST (SSOaaS)	✔	✔	✔	✔		Enables both DevOps and Service Token
DevOpsCDA (SSOaaS)	✔	✔	✔	✔		Enables both DevOps and CDA
OAuth2 [17]	✔	✔	✔		✔	Uses OpenID Connect/OAuth2 access token to check authentication and authorization, can be used to protect Web Services
Secure Token	✔	✔	✔			Designed to secure exchanges between a LLNG reverse-proxy and a remote app
Service Token (Server-to-Server)	✔	✔	✔	✔	✔	Designed to permit underlying requests (API-Based Infrastructure)
Zimbra PreAuth	✔	✔	✔

LLNG databases¶

Configuration database¶

LL::NG needs a storage system to store its own configuration (managed by the manager). Choose one in the following list:

Backend	Shareable	Comment
File (JSON)		Not shareable between servers except if used in conjunction with REST or with a shared file system (NFS,…). Selected by default during installation.
YAML		Same as File but in YAML format instead of JSON
SQL (CDBI/RDBI)	✔	Recommended for large-scale systems. Prefer CDBI.
Cassandra	✔	Via SQL pseudo-driver
LDAP	✔
MongoDB	✔
SOAP	✔	Proxy backend to be used in conjunction with another configuration backend. Can be used to secure another backend for remote servers.
REST	✔	Proxy backend to be used in conjunction with another configuration backend. Can be used to secure another backend for remote servers.
Local		Use only lemonldap-ng.ini parameters.

Tip

You can not start with an empty configuration, so read how to change configuration backend to convert your existing configuration into another one.

Sessions database¶

Sessions are stored using Apache::Session modules family. All Apache::Session style modules are usable except for some features.

Attention

If you plan to use LLNG in a large-scale system, take a look at Performance Test to choose the right backend. A Browseable SQL backend is generally a good choice.

Backend	Shareable	Session explorer	Session restrictions	Session expiration	Comment
File		✔	✔	✔	Not shareable between servers except if used in conjunction with REST session backend or with a shared file system (NFS,…). Selected by default during installation.
PgJSON	✔	✔	✔	✔	Recommended backend for production installations
Browseable MySQL	✔	✔	✔	✔	Recommended for those who prefer MySQL
Browseable LDAP	✔	✔	✔	✔
Redis	✔	✔	✔	✔	The fastest. Must be secured by network access control.
MongoDB	✔	✔	✔	✔	Must be secured by network access control.
Cassandra	✔	✔	✔	✔	Another supported NoSQL DB
SQL	✔	✔	✔	✔	Unoptimized for session explorer and single session features.
REST	✔	✔	✔	✔	Proxy backend to be used in conjunction with another session backend.
SOAP	✔	✔	✔	✔	Proxy backend to be used in conjunction with another session backend.

Tip

You can migrate from one session backend to another using the session conversion script. ( since 2.0.7)

Applications protection¶

• Writing rules and headers
• Variables that can be used in rules and headers
• Integrate vendor applications
• Integrate self-made applications
• Form replay
• Custom Handlers
• WebServices / API
• WebSocket Applications

Advanced features¶

• SMTP server setup
• Notifications system
• Store password in session
• Cross Domain Authentication (CDA)
• Role Based Access Control (RBAC)
• Use custom functions
• Use extended functions
• Reset password by mail (self service)
• Create an account (self service)
• Forward logout to applications
• Secure Token Handler
• AuthBasic Handler
• SSO as a Service (SSOaaS)
• Handling server webservice calls
• LemonLDAP::NG kubernetes controller
• Safe jail
• Login history
• Fast CGI support
• Advanced PSGI usage
• Ignore some manager tests
• See full parameters list
• Installation from the tarball
• Installation on Suse Linux Enterprise Server with packages
• Deploy Traefik configuration
• Deploy LemonLDAP::NG on Plack servers family (Twiggy, Starman, Corona,…)
• Node.js handler

Mini howtos¶

• Command Line Interface (lemonldap-ng-cli) examples
• Modify Manager protection
• Configuration and sessions in MySQL
• Configuration and sessions in LDAP
• Configuration and sessions access by REST
• Integration in Active Directory (LDAP and Kerberos)
• Create a protocol proxy (SAML to OpenID, CAS to SAML ,…)
• Convert HTTP header into environment variable
• Connect to Renater Federation
• Run LemonLDAP::NG components behind a reverse proxy
• Configure LL::NG to use an outgoing proxy

Exploitation¶

• Performances
• Security
• SELinux
• Handler status page
• Portal state check (health check for fail-over)
• Monitoring
• Logs settings
• Error messages
• High Availability

Bug report¶

See How to report a bug.

Developer corner¶

To contribute, see :

• Contribute to project

To develop an handler, see:

• Handler architecture
• Custom handlers

To develop a portal plugin, see manpages:

• Lemonldap::NG::Portal
• Lemonldap::NG::Portal::Auth
• Lemonldap::NG::Portal::UserDB
• Lemonldap::NG::Portal::Main::SecondFactor
• Lemonldap::NG::Portal::Main::Issuer
• Lemonldap::NG::Portal::Main::Plugin
• Lemonldap::NG::Portal::Main::Request (the request object)

To add a new language:

• Join us on https://app.transifex.com/lemonldapng/lemonldapng/dashboard/
• translate the 3 files
• then we will append them in sources.

If you don’t want to publish your translation (XX must be replaced by your language code):

• Manager: translate lemonldap-ng-manager/site/htdocs/static/languages/en.json in lemonldap-ng-manager/site/htdocs/static/languages/XX.json and enable it in “lemonldap-ng.ini” file
• Portal: translate lemonldap-ng-portal/site/htdocs/static/languages/en.json in lemonldap-ng-portal/site/htdocs/static/languages/XX.json and enable it in “lemonldap-ng.ini” file
• Portal Mails: translate lemonldap-ng-portal/site/templates/common/mail/en.json in lemonldap-ng-portal/site/templates/common/mail/XX.json