# Presentation

LemonLDAP::NG is a modular WebSSO (Single Sign On) based on Apache::Session modules. It simplifies the build of a protected area with a few changes in the application.

It manages both authentication and authorization and provides headers for accounting. So you can have a full AAA protection for your web space as described below.

## Architecture

### Main components

- Manager: used to manage LemonLDAP::NG configuration and to explore sessions. Dedicated to administrators
- Portal: used to authenticate users, display applications list and provides identity provider service (SAML, OpenID, CAS). Portal provides also many other features (see portal for more)
- Handler: Apache modules used to protect applications

### Databases

We call “database” a backend where we can read or write a data. This can be a file, an LDAP directory, …

We split databases in two categories:

- External databases: not managed by LemonLDAP::NG, for example user database
- Internal databases: only used by LemonLDAP::NG

Main external databases are:

- Authentication: how authenticate users
- User: where collect user data
- Password: where change the password

Main internal databases are:

- Configuration: where configuration is stored. This does not include Apache configuration which is not managed by LemonLDAP::NG
- Sessions: where sessions are stored.
- Notifications: messages displayed to connected users
- Cache: cache for configuration and sessions

## Kinematics

### Login

1. User tries to access protected application, his request is catched by Handler
2. SSO cookies is not detected, so Handler redirects user to Portal
3. User authenticates on Portal
4. Portal checks authentication
5. If authentication succeed, Portal collect user data
6. Portal creates a session to store user data
7. Portal gets the session key
8. Portal creates SSO cookies with session key as value
9. User is redirected on protected application, with his new cookie
10. Handler gets session get from cookie and gets session
11. Handler stores user data in its cache
12. Handler check access rule and send headers to protected applications
13. Protected application sends response to Handler
14. Handler sends the response to user

Handler will then check SSO cookies for each HTTP request.

### Logout

Default use case:

1. User clicks on the logout link in Portal
2. Portal destroys session and redirects user on itself with an empty SSO cookies
3. User is redirected on portal and his SSO cookies is empty

LemonLDAP::NG is also able to catch logout request on protected applications, with different behavior:

- SSO logout: the request is not forwarded to application, only the SSO session is closed
- Application logout: the request is forwarded to application but SSO session is not closed
- SSO and Application logout: the request is forwarded to application and SSO session is closed

After logout process, the user is redirected on portal, or on a configured URL.

### Session expiration

The session expires after 2 hours by default.

- Handlers have a session cache, with a default lifetime of 10 minutes. So for Handler on different physical servers than the Portal, a user with an expired session can still be authorized still the cache expires.
- Sessions are deleted by a scheduled task. Don't forget to install cron files !

### Cross Domain Authentication (CDA)

For security reason, a cookie provided for a domain cannot be sent to another domain. To extend SSO on several domains, a cross-domain mechanism is implemented in LemonLDAP::NG.

1. User owns SSO cookies on the main domain (see Login kinematics)
2. User tries to access a protected application in a different domain
3. Handler does not see SSO cookies (because it is not in main domain) and redirects user on Portal
4. Portal recognizes the user with its SSO cookies, and see he is coming from a different domain
5. Portal redirects user on protected application with his session ID as URL parameter
6. Handler detects URL parameter and create a SSO cookies on its domain, with session ID as value

## Authentication, Authorization and Accounting (AAA) mechanisms

### Authentication

If a user is not authenticated and attempts to connect to an area protected by a LemonLDAP::NG compatible Handler, he is redirected to a portal.

Authentication process main steps are:

- Control asked URL: prevent XSS attacks and bad redirections
- Control existing session: detect SSO session, apply configured constraints (1 session per user, 1 session per IP, …)
- Extract form info: get login/password, certificate, environment variable (depending on authentication module)
- Get user info: contact user database to collect attributes
- Set macros: compute configured macros
- Set groups: request user database to find groups
- Set local groups: compute configured groups
- Authenticate: contact authentication database to check credentials
- Grant session: check rights to open SSO session
- Store: store user info in session database
- Build cookie: build SSO cookies with session ID
- Redirect: redirect user on protected application or on Portal (applications menu)

LemonLDAP::NG SSO cookies are generated by Apache::Session, they are as secure as a 128-bit random cookie. You may use the securedCookie options to avoid session hijacking.

### Authorization

Authorization is controlled only by Handlers. An authorization is defined by:

- An URL pattern (or `default` to match other URLs)
- An access rule

Authorizations are defined inside a virtualhost and takes effect only on it. There are no global authorizations except the right to open a session in the portal.

Access rules values can be:

- `accept`: all authenticated users can pass
- `deny`: nobody is welcomed
- `skip`: all is open!
- `unprotect`: all is open, but authenticated users are seen as authenticated
- `logout_sso`, `logout_app`, `logout_app_sso`: catch logout request
- Perl expression: perl code snippet that returns 0 or 1

Some examples:

- Accept all authenticated users:
  - URL pattern: `default`
  - Access rule: `accept`
- Restrict /admin to administrators group
  - URL pattern: `^/admin/`
  - Access rule: `$groups =~ /\badministrators\b/`

`\b` means start or end of a word in PCRE (Perl Compatible Regular Expressions)

See Writing rules and headers chapter.

### Accounting

#### Logging portal access

Portal produce a `notice` message in Apache logs or syslog when a user authenticates (or fails to authenticate) and logs out.

#### Logging application access

Handler inform Apache of connected user (parameter `whatToTrace`), so you can see user login in Apache access logs.

The real accounting has to be done by the application itself since SSO logs can not understand transactions.

LemonLDAP::NG can export HTTP headers either using a proxy or protecting directly the application.

An HTTP header is defined by:

- A name
- A value

Headers are defined inside a virtualhost and takes effect only on it. There are no global headers.

The header value is a Perl expression, returning a string.

Some examples:

- Send login in Auth-User:
  - Name: `Auth-User`
  - Value: `$uid`
- Send “Lastname, firstname” in Auth-Name:
  - Name: `Auth-Name`
  - Value: `$sn + “, ” + $gn`

See Writing rules and headers for more.