lemonldap-ng/doc/sources/admin/writingrulesand_headers.rst

232 lines
9.4 KiB
ReStructuredText
Raw Normal View History

2020-05-14 23:29:41 +02:00
Writing rules and headers
=========================
2022-03-03 23:29:48 +01:00
LL::NG manages applications by their hostname (Apache Virtual Hosts or
Nginx Block Servers). Rules are used for protecting applications,
2022-03-03 22:29:45 +01:00
and HTTP headers are appended to each request for sending datas to protected
applications (for logs, profiles,...).
2020-05-14 23:29:41 +02:00
2020-05-21 15:13:24 +02:00
.. attention::
2020-05-14 23:29:41 +02:00
Note that variables designed by $xx correspond to the
name of the :doc:`exported variables<exportedvars>` or
2020-05-18 09:56:39 +02:00
:ref:`macro names<macros_and_groups>` except for ``$ENV{<cgi-header>}`` which
2022-03-03 22:29:45 +01:00
correspond to CGI headers (``$ENV{REMOTE_ADDR}`` for example).
2020-05-14 23:29:41 +02:00
Available $ENV variables
------------------------
2022-03-03 22:29:45 +01:00
The %ENV hash provides:
2020-05-14 23:29:41 +02:00
2020-05-18 09:56:39 +02:00
- all headers in CGI format (``User-Agent`` becomes
``HTTP_USER_AGENT``)
2020-05-14 23:29:41 +02:00
- some CGI variables depending on the context:
2020-05-18 09:56:39 +02:00
- For portal: all CGI standard variables (you can add custom
headers using ``fastcgi_param`` with Nginx),
2020-05-14 23:29:41 +02:00
- For Apache handler: REMOTE_ADDR, QUERY_STRING, REQUEST_URI,
SERVER_PORT, REQUEST_METHOD,
- For Nginx handler: all variables given by ``fastcgi_param``
commands.
2022-03-03 22:29:45 +01:00
- For Portal:
2020-05-14 23:29:41 +02:00
- $ENV{urldc} : Origin URL before Handler redirection, in cleartext
- $ENV{_url} : Origin URL before Handler redirection, base64 encoded
See also :doc:`extended functions<extendedfunctions>`.
2020-05-18 09:56:39 +02:00
.. _rules:
2020-05-14 23:29:41 +02:00
Rules
-----
A rule associates a `regular
expression <http://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions>`__
to a Perl boolean expression or a keyword.
|image0|
Examples:
=============================================================================================================================================== ================== ======================================
Goal Regular expression Rule
=============================================================================================================================================== ================== ======================================
2020-05-18 09:56:39 +02:00
Restrict /admin/ directory to user bart.simpson ^/admin/
2020-05-14 23:29:41 +02:00
Restrict /js/ and /css/ directory to authenticated users ^/(css|js)/ accept
Deny access to /config/ directory ^/config/ deny
Do not restrict /public/ ^/public/ skip
Do not restrict /skip/ and restrict other to authenticated users ^/skip/ $ENV{REQUEST_URI} =~ /skip/ ? skip : 1
Makes authentication optional, but authenticated users are seen as such (that is, user data are sent to the app through HTTP headers) ^/forum/ unprotect
2020-05-18 09:56:39 +02:00
Restrict access to the whole site to users that have the LDAP description field set to "LDAP administrator" (must be set in exported variables) default
2020-05-14 23:29:41 +02:00
=============================================================================================================================================== ================== ======================================
2022-03-03 22:29:45 +01:00
The "**default**" access rule is used if none rule matches the
2020-05-14 23:29:41 +02:00
current URL.
2020-05-18 09:56:39 +02:00
.. tip::
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
See :doc:`the rule examples page<rules_examples>` for few
2020-05-18 09:56:39 +02:00
common use cases
.. tip::
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
- Comments can be employed for ordering your rules: rules are applied depending on
comment alphabetical order (or regexp if no comment is defined). See
2020-05-18 09:56:39 +02:00
:ref:`security chapter<security-write-good-rules>` to learn more
2022-03-03 22:29:45 +01:00
about rules best practice.
- See :ref:`performances<performances-handler-performance>` to learn how
using macros and groups in rules.
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
Rules can also be used for intercepting logout URL:
2020-05-14 23:29:41 +02:00
2020-10-19 18:33:55 +02:00
================================================================================================================= =================== =====================================
2020-05-14 23:29:41 +02:00
Goal Regular expression Rule
2020-10-19 18:33:55 +02:00
================================================================================================================= =================== =====================================
Logout user from Lemonldap::NG and redirect it to http://intranet/ ^/index.php\?logout logout_sso http://intranet/
Logout user from current application and redirect it to the menu **(Apache only)** ^/index.php\?logout logout_app https://auth.example.com/
Logout user from current application and from Lemonldap::NG and redirect it to http://intranet/ **(Apache only)** ^/index.php\?logout logout_app_sso http://intranet/
================================================================================================================= =================== =====================================
2020-05-14 23:29:41 +02:00
2020-05-21 15:13:24 +02:00
.. danger::
2020-05-14 23:29:41 +02:00
\ ``logout_app`` and ``logout_app_sso`` rules are not
2022-03-03 22:29:45 +01:00
available with Nginx, Apache ONLY.
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
By default, users will be redirected to the Portal if no URL is defined,
or to the specified URL if exists.
2020-05-14 23:29:41 +02:00
2020-05-21 15:13:24 +02:00
.. attention::
2020-05-14 23:29:41 +02:00
Only current application is concerned by logout_app\*
2022-03-03 22:29:45 +01:00
targets. Be careful with some applications which does not check
headers sent by LL::NG after having created their own application cookies.
If so, you can redirect users to a HTML page that explain that it is better
to close browser after logout.
2020-05-14 23:29:41 +02:00
Rules based on authentication level
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2022-03-03 22:29:45 +01:00
LL::NG set an "authentication level" during authentication process. This
2020-05-14 23:29:41 +02:00
level depends on authentication backend used by this user. Default
values are:
- 0 for :doc:`Null<authnull>`
- 1 for :doc:`CAS<authcas>`, :doc:`old OpenID-2<authopenid>`,
:doc:`Facebook<authfacebook>`,…
2020-05-18 09:56:39 +02:00
- 2 for web-form based authentication (:doc:`LDAP<authldap>`,
:doc:`DBI<authdbi>`,…)
2020-05-14 23:29:41 +02:00
- 3 for :doc:`Yubikey<authyubikey>`
- 4 for :doc:`Kerberos<authapache>`
- 5 for :doc:`SSL<authssl>`
There are three ways to impose users a higher authentication level:
- writing a rule based on authentication level:
``$authenticationLevel > 3``
- since 2.0, set a minimum level in virtual host options (default value
for ALL access rules)
- since 2.0.7, a minimum authentication level can be set for each URI
access rule. Useful if URI are protected by different types of
handler (AuthBasic -> level 2, Main -> level set by authentication
backend).
2020-05-18 09:56:39 +02:00
.. tip::
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
Instead of returning a 403 code, "minimum level" returns users
to a form that explains that a higher level is required and propose to
2020-05-14 23:29:41 +02:00
reauthenticate himself.
2020-05-18 09:56:39 +02:00
.. _headers:
2020-05-14 23:29:41 +02:00
Headers
-------
Headers are associations between an header name and a perl expression
2022-03-03 22:29:45 +01:00
that returns a value. Headers are used for sending user data to protected
applications.
2020-05-14 23:29:41 +02:00
Examples:
============================= ============ =======================
Goal Header name Header value
============================= ============ =======================
Give the uid (for accounting) Auth-User $uid
Give a static value Some-Thing "static-value"
Give display name Display-Name $givenName." ".$surName
Give a non ascii data Display-Name
============================= ============ =======================
2020-05-18 09:56:39 +02:00
As described in
:ref:`performances chapter<performances-handler-performance>`, you can
use macros, local macros,...
2020-05-21 15:13:24 +02:00
.. attention::
2020-05-14 23:29:41 +02:00
- Since many HTTP servers refuse non ascii headers, it is recommended
to use encode_base64() function to transmit those headers
2022-03-03 22:29:45 +01:00
- Do not forget to add an empty string as second argument to
2020-05-14 23:29:41 +02:00
encode_base64 function to avoid a "newline" characters insertion in
result
2020-12-10 09:12:42 +01:00
- Header names must contain only letters and "-" character.
With Nginx, you can bypass this restriction by using
``underscores_in_headers on;`` directive
2020-05-14 23:29:41 +02:00
2020-05-18 09:56:39 +02:00
.. tip::
2020-05-14 23:29:41 +02:00
By default, SSO cookie is hidden. So protected applications
cannot retrieve SSO session key. But you can forward this key if
2022-03-03 22:29:45 +01:00
absolutely needed (NOT recommanded because can be a security issue):
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
::
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
Session-ID => $_session_id
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
Available functions
-------------------
In addition to macros and name, you can use some functions in rules and
headers:
2022-03-03 22:29:45 +01:00
- :doc:`LL::NG extended functions<extendedfunctions>`
2020-05-14 23:29:41 +02:00
- :doc:`Your custom functions<customfunctions>`
Wildcards in hostnames
----------------------
|image1| Since 2.0, a wildcard can be used in virtualhost name (not in
aliases !): ``*.example.com`` matches all hostnames that belong to
``example.com`` domain. Version 2.0.9 improves this and allows better
wildcards such as ``test-*.example.com`` or ``test-%.example.com``. The
``%`` wilcard doesn't match subdomains.
2022-03-03 22:29:45 +01:00
Even if a wildcard exists, if a VirtualHost is explicitly declared, this
rule will be applied. Example with precedence order for test.sub.example.com:
2020-05-14 23:29:41 +02:00
#. test.sub.example.com
#. test%.sub.example.com
#. test*.sub.example.com
#. %.sub.example.com
#. \*.sub.example.com
2020-05-18 09:56:39 +02:00
#. \*.example.com (``%.example.com`` does not match
test.sub.example.com)
2020-05-14 23:29:41 +02:00
.. |image0| image:: /documentation/manager-rule.png
:class: align-center
.. |image1| image:: /documentation/new.png
:width: 35px