documentation:2.0:start
Keywords: documentation,2.0,start

# Documentation for LemonLDAP::NG 2.0

## Presentation

- Presentation
- Main features
- Quick start tutorial
- Choose a platform

## Installation

### Before installation

- Prerequisites and dependencies
- Upgrade notes

### Installation

- Installation from the tarball
- Installation on Debian/Ubuntu with packages
- Installation on RHEL/CentOS with packages
- Installation on Suse Linux Enterprise Server with packages
- Run in LemonLDAP::NG in Docker
- Node.js handler

### After installation

- Deploy Nginx configuration (recommended configuration)
- Deploy Apache configuration
- Deploy LemonLDAP::NG on Plack servers family (Twiggy, Starman, Corona,...)

## Configuration

### First steps

- Configuration overview
- Configure Single Sign On cookie and portal URL
- Parameter redirections
- Set exported variables
- Manage virtual hosts
- Configure sessions specificities

### 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 | ✔ | ✔ |
GPG (introduced in 2.0.2) | ✔ |  |
Kerberos | ✔ |  |
LDAP | ✔ | ✔ | ✔
LinkedIn | ✔ |  |
Null | ✔ | ✔ | ✔
OpenID Connect | ✔ | ✔ |
PAM | ✔ |  |
Proxy LL::NG | ✔ | ✔ |
Radius | ✔ |  |
REST | ✔ | ✔ | ✔
SAML 2.0 / Shibboleth | ✔ | ✔ |
Slave | ✔ | ✔ |
SSL | ✔ |  |
Twitter | ✔ |  |
WebID | ✔ | ✔ |
Yubikey | Deprecated, replaced by Yubikey second factor
Custom modules | ✔ | ✔ | ✔
Combo Backends | Authentication | Users | Password
Choice by users | ✔ | ✔ | ✔
Combination of auth schemes | ✔ | ✔ |
Multiple backends stack | Deprecated, replaced by Combination
Obsolete Backends | Authentication | Users | Password
OpenID | ✔ | ✔ |
Remote LL::NG | ✔ | ✔ |
Second factor (documentation) | Authentication |  |
TOTP-or-U2F | ✔ |  |
U2F | ✔ |  |
TOTP (Google Authenticator,...) | ✔ |  |
E-mail Second Factor | ✔ |  |
External Second Factor (OTP, SMS,...) | ✔ |  |
REST Second Factor | ✔ |  |
Yubikey | ✔ |  |
Auth addons | Authentication |  |
Auto Signin | ✔ |  |

#### Identity provider

- 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 2.0 (obsolete) | ✔ | ✔
OpenID Connect | ✔ | ✔
Get parameters provider (for poor applications) |  | ✔

#### Attacks and Protection

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 | ✔ |

#### Plugins

Name | Description
--- | ---
Auto Signin | Auto Signin Addon
Brute Force protection | User must wait to log in after 3 failed login attempts
CDA | Cross Domain Authentication
Check state | Check state plugin (test page)
Custom | Write a custom plugin
Force Authentication | Force authentication to access to Portal
Display login history |
Grant Sessions rules |
Notifications system |
Public pages | Enable public pages system
Reset password by mail |
REST services | REST server for Proxy
SOAP services (deprecated) | SOAP server for Proxy
Portal Status | Experimental portal status page
Stay connected | Enable persistent connection on same browser
Upgrade session | Plugin that explain to user that a more secure authentication is needed instead of rejected it

### Handlers

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

Handler type | Apache | Nginx | Plack* servers | Node.js | Comment |
Main (default handler) | ✔ | ✔ | ✔ | Partial (*) |  |
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 |
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 | ✔ | ✔ | ✔ |  |

(*): Node.js handler has not yet reached the same level of functionalities.

### 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 (RDBI/CDBI) | ✔ | Recommended for large-scale systems. Prefer CDBI.
LDAP | ✔ |
MongoDB | ✔ |
SOAP (deprecated) | ✔ | 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.

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.

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.
SQL | ✔ | ✔ | ✔ | ✔ | Unoptimized for session explorer and single session features.
LDAP | ✔ | ✔ | ✔ | ✔
Redis | ✔ | ✔ | ✔ | ✔ | The fastest. Must be secured by network access control.
MongoDB | ✔ | ✔ | ✔ | ✔ | Must be secured by network access control.
Browseable (SQL, Redis or LDAP) | ✔ | ✔ | ✔ | ✔ | Optimized for session explorer and single session features.
REST | ✔ | ✔ | ✔ | ✔ | Proxy backend to be used in conjunction with another session backend. Can be used to secure another backend for remote servers.
SOAP (deprecated) | ✔ | ✔ | ✔ | ✔ | Proxy backend to be used in conjunction with another session backend. Can be used to secure another backend for remote servers.

## 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

### Well known compatible applications

Here is a list of well known applications that are compatible with LL::NG. A full list is available on vendor applications page.

## 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

## 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

## 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 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://www.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`