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 ------------ |image0| Main components ~~~~~~~~~~~~~~~ - **Manager**: used to manage LemonLDAP::NG configuration and to explore sessions. Dedicated to administrators - :doc:`Portal`: used to authenticate users, display applications list and provides identity provider service (`SAML `__, `OpenID `__, `CAS `__). Futhermore, Portal affordes many other features (see :doc:`portal` for more) - :doc:`Handler`: used to protect applications which can read HTTP headers or environment variables to get user information Databases ~~~~~~~~~ .. attention:: We call "database" a backend where we can read or write a data. This can be a file, an LDAP directory, etc. 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 :ref:`external databases` are: - **Authentication**: how authenticate users - **User**: where collect user data - **Password**: where change the password Main internal databases are: - :ref:`Configuration`: where configuration is stored. This does not include web server configuration which is not managed by LemonLDAP::NG - :ref:`Sessions`: where sessions are stored. - :doc:`Notifications`: messages displayed to connected users - **Cache**: cache for configuration and sessions .. _presentation-kinematics: Kinematics ---------- .. _presentation-login: Login ~~~~~ |image1| #. User tries to access protected application, his request is catched by Handler #. :doc:`SSO cookies` is not detected, so Handler redirects user to Portal #. User authenticates on Portal #. Portal checks authentication #. If authentication succeed, Portal collect user data #. Portal creates a session to store user data #. Portal gets the session key #. Portal creates :doc:`SSO cookies` with session key as value #. User is redirected on protected application, with his new cookie #. Handler reads session key from cookie and retrieves user session datas #. Handler stores user datas in its cache #. Handler check access rule and send headers to protected application #. Protected application sends response to Handler #. Handler forwards the response to user Then handler will check :doc:`SSO cookies` for each HTTP request. Logout ~~~~~~ Default use case: #. User clicks on the logout link in Portal #. Portal destroys session and redirects user on itself with an empty :doc:`SSO cookies` #. User is redirected on portal and his :doc:`SSO cookies` is empty LemonLDAP::NG is also able to :doc:`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 20 hours by default. This duration can be set in the manager's Configuration tab (General Parameters > Sessions > Sessions Timeout). .. attention:: - Handlers have a session cache, with a default lifetime of 10 minutes. So for Handlers located on different physical servers than the Portal, a user with an expired session can still be authorized until the cache expires. - Sessions are deleted by a scheduled task. Don't forget to install cron files ! .. _cda: Cross Domain Authentication (CDA) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: 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. #. User owns :doc:`SSO cookies` on the main domain (see :ref:`Login kinematics`) #. User tries to access a protected application in a different domain #. Handler does not see :doc:`SSO cookies` (because it is not in main domain) and redirects user on Portal #. Portal recognizes the user with its :doc:`SSO cookies`, and see he is coming from a different domain #. Portal redirects user on protected application with a token as URL parameter. The token is linked to a session which contains the real session ID #. Handler detects URL parameter, gets the real session ID, delete the token session and creates a :doc:`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 - **Ask for second factor if required**: TOTP, U2F key, etc... - **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 :doc:`SSO cookies` with session ID - **Redirect**: redirect user on protected application or on Portal (applications menu) LemonLDAP::NG :doc:`SSO cookies` are generated by `Apache::Session `__, they are as secure as a 128-bit random cookie. You may use the :doc:`securedCookie` options to avoid session hijacking. (since version 1.4.0 you can use SHA256 for generating safer cookies) Authorization ~~~~~~~~~~~~~ Authorization is controlled only by Handlers. An authorization is defined by: - An URL pattern (or ``default`` to match other URLs) - An access rule .. note:: 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/`` .. tip:: \ ``\b`` means start or end of a word in PCRE (Perl Compatible Regular Expressions) See :doc:`Writing rules and headers` chapter. Accounting ~~~~~~~~~~ Logging portal access ^^^^^^^^^^^^^^^^^^^^^ Portal produce a ``notice`` message in :doc:`Web server logs or syslog` when a user authenticates (or fails to authenticate) and logs out. Logging application access ^^^^^^^^^^^^^^^^^^^^^^^^^^ Handler informs Web server of connected user (parameter ``whatToTrace``), so you can see user login in Web server access logs. The real accounting has to be done by the application itself since SSO logs can not understand transactions. LemonLDAP::NG can export :ref:`HTTP headers` either using a proxy or protecting directly the application. An HTTP header is defined by: - A name - A value .. note:: Headers are defined inside a virtualhost and take 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 :doc:`Writing rules and headers` for more. .. |image0| image:: documentation/lemonldap-ng-architecture.png :class: align-center :width: 600px .. |image1| image:: documentation/lemonldapng-sso.png :class: align-center :width: 800px