# 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 | ✔ | ✔ |
GitHub 1) | ✔ |  |
GPG 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,...) | ✔ |  |
Radius Second Factor 3) | ✔ |  |
REST Second Factor | ✔ |  |
Yubikey | ✔ |  |
Additional second factors 4) | ✔ |  |
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) |  | ✔

* Issuers timeout : Delay for issuers to submit their authentication requests

* 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

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 some failed login attempts
CDA | Cross Domain Authentication
Check state | Check state plugin (test page)
Check user 5) | 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 6) | Switch context other users
Custom | Write a custom plugin
Decrypt value 7) | Decrypt ciphered values
Display login history |
Force Authentication | Force authentication to access to Portal
Global Logout 8) | Suggest to close all opened sessions at logout
Grant Sessions | Rules to apply before allowing a user to open a session
Impersonation 9) | Allow users to use another identity
Notifications system |
Portal Status | Experimental portal status page
Public pages | Enable public pages system
Refresh session API 10) | Plugin that provides an API to refresh a user session
Reset password by mail |
Reset certificate by mail 11) | Allow users to reset their certificate
REST services | REST server for Proxy
SOAP services (deprecated) | SOAP server for Proxy
Stay connected | Enable persistent connection on same browser
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, Apache, PSGI like Plack based servers or Node.js).

Handler type | Apache | LLNG FastCGI/uWSGI server (Nginx, or SSOaaS) | Plack* servers | Node.js (express apps or SSOaaS) | Self protected apps | Comment
--- | --- | --- | --- | --- | --- | ---
Main (default handler) | ✔ | ✔ | ✔ | Partial 12) | ✔ |
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
OAuth2 13) | ✔ | ✔ | ✔ |  | ✔ | 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 (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.

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

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

1) GitHub authentication is available with LLNG ≥ 2.0.8
2) GPG authentication is available with LLNG ≥ 2.0.2
3) Radius second factor is available with LLNG ≥ 2.0.6
4) Additional second factors are available with LLNG ≥ 2.0.6
5) Check user plugin is available with LLNG ≥ 2.0.3
6) Context switching plugin is available with LLNG ≥ 2.0.6
7) Decrypt value plugin is available with LLNG ≥ 2.0.7
8) Global Logout plugin is available with LLNG ≥ 2.0.7
9) Impersonation plugin is available with LLNG ≥ 2.0.3
10) Refresh session API plugin is available with LLNG ≥ 2.0.7
11) Reset certificate by mail plugin is available with LLNG ≥ 2.0.7
12) Node.js handler has not yet reached the same level of functionalities
13) OAuth2 Handler is available with LLNG ≥ 2.0.4