Differences

This shows you the differences between two versions of the page.

Link to this comparison view

documentation:2.1:writingrulesand_headers [2019/01/15 15:55] (current)
Line 1: Line 1:
 +====== Writing rules and headers ======
  
 +Lemonldap::​NG manage applications by their hostname (Apache'​s virtualHosts). Rules are used to protect applications,​ headers are HTTP headers added to the request to give datas to the application (for logs, profiles,​...).
 +
 +<note important>​Note that variables designed by $xx correspond to the name of the [[exportedvars|exported variables]] or [[performances#​macros_and_groups|macro names]] except for ''​$ENV{<​cgi-header>​}''​ which correspond to CGI header //​(''​$ENV{REMOTE_ADDR}''​ for example)//​.</​note>​
 +
 +===== Available $ENV{} variables =====
 +
 +The %ENV table provides:
 +  * all headers in CGI format //​(''​User-Agent''​ becomes ''​HTTP_USER_AGENT''​)//​
 +  * some CGI variables depending on the context:
 +    * For portal: all CGI standard variables //(you can add custom headers using ''​fastcgi_param''​ with Nginx)//,
 +    * For Apache handler: REMOTE_ADDR,​ QUERY_STRING,​ REQUEST_URI,​ SERVER_PORT,​ REQUEST_METHOD,​
 +    * For Nginx handler: all variables given by ''​fastcgi_param''​ commands.
 +  * For portal:
 +    * $ENV{urldc} : Origin URL before Handler redirection,​ in cleartext
 +    * $ENV{_url} : Origin URL before Handler redirection,​ base64 encoded
 +
 +See also [[extendedfunctions|extended functions]].
 +
 +===== Rules =====
 +
 +A rule associates a [[http://​en.wikipedia.org/​wiki/​Perl_Compatible_Regular_Expressions|regular expression]] to a Perl boolean expression or a keyword.
 +
 +{{ :​documentation:​manager-rule.png |}}
 +
 +Examples:
 +
 +^  Goal  ^  Regular expression ​ ^  Rule  ^
 +| Restrict /admin/ directory to user bart.simpson ​ |  <​nowiki>​^/​admin/</​nowiki> ​ |  <​html>​$uid&​nbsp;​eq&​nbsp;"​bart.simpson"</​html> ​ |
 +| Restrict /js/ and /css/ directory to authenticated users  |  <​nowiki>​^/​(css|js)/</​nowiki> ​ |  accept ​ |
 +| Deny access to /config/ directory ​ |  <​nowiki>​^/​config/</​nowiki> ​ |  deny  |
 +| Do not restrict /​public/ ​ |  <​nowiki>​^/​public/</​nowiki> ​ |  skip  |
 +| Makes authentication optional, but authenticated users are seen as such (that is, user data are sent to the app through HTTP headers) ​ |  <​nowiki>​^/​forum/</​nowiki> ​ |  unprotect ​ |
 +| 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 ​ |  <​html>​$description&​nbsp;​eq&​nbsp;"​LDAP&​nbsp;​administrator"</​html> ​ |
 +
 +The "​**default**"​ access rule is used if no other access rule match the current URL.
 +
 +<note tip>
 +  * Comments can be used to order your rules: rules are applied in the alphabetical order of comment (or regexp in there is no comment). See **[[security#​write_good_rules|security chapter]]** to learn more about writing good rules.
 +  * See [[performances#​handler_performance|performances]] to know how to use macros and groups in rules.
 +</​note>​
 +
 +Rules can also be used to intercept logout URL:
 +
 +^  Goal  ^  Regular expression ​ ^  Rule  ^
 +| Logout user from Lemonldap::​NG and redirect it to <​nowiki>​http://​intranet/</​nowiki> ​ |  <​nowiki>​^/​index.php\?​logout</​nowiki> ​ |  <​html>​logout_sso&​nbsp;​http://​intranet/</​html> ​ |
 +| Logout user from current application and redirect it to the menu **//(Apache only)//​** ​ |  <​nowiki>​^/​index.php\?​logout</​nowiki> ​ |  <​html>​logout_app&​nbsp;​https://​auth.example.com/</​html> ​ |
 +| Logout user from current application and from Lemonldap::​NG and redirect it to <​nowiki>​http://​intranet/</​nowiki>​ **//(Apache only)//** |  <​nowiki>​^/​index.php\?​logout</​nowiki> ​ |  <​html>​logout_app_sso&​nbsp;​http://​intranet/</​html> ​ |
 +
 +<note warning>''​logout_app''​ and ''​logout_app_sso''​ rules are not available on Nginx, only on Apache.</​note>​
 +
 +By default, user will be redirected on portal if no URL defined, or on the specified URL if any.
 +
 +<note important>​Only current application is concerned by logout_app* targets. Be careful with some applications which doesn'​t verify Lemonldap::​NG headers after having created their own cookies. If so, you can redirect users to a HTML page that explain that it is safe to close browser after disconnect.</​note>​
 +
 +==== Rules on authentication level ====
 +
 +LLNG set an "​authentication level" during authentication process. This level is the value of the authentication backend used for this user. Default values are:
 +  * 0 for [[authnull|Null]]
 +  * 1 for [[authcas|CAS]],​ [[authopenid|old OpenID-2]], [[authfacebook|Facebook]],​…
 +  * 2 for web-form based authentication //​([[authldap|LDAP]],​ [[authdbi|DBI]],​…)//​
 +  * 3 for [[authyubikey|Yubikey]]
 +  * 4 for [[authapache|Kerberos]]
 +  * 5 for [[authssl|SSL]]
 +
 +There are two way to impose users to have a high authentication level:
 +  * writing a rule based en authentication level: ''​$authenticationLevel > 3''​
 +  * since 2.0, set a minimum level in virtual host options
 +
 +<note tip>​Instead of returning a 403 code, "​minimum level" returns user to a form that explain that a higher level is required and propose to user to reauthenticate itself.</​note>​
 +
 +===== Headers =====
 +
 +Headers are associations between an header name and a perl expression that returns a string. Headers are used to give user datas to the application. ​
 +
 +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 ​ |  <​html>​encode_base64($givenName."&​nbsp;"​.$surName,""​)</​html> ​ |
 +
 +As described in [[performances#​handler_performance|performances chapter]], you can use macros, local macros,...
 +
 +<note important>​
 +  * Since many HTTP servers refuse non ascii headers, it is recommended to use encode_base64() function to transmit those headers
 +  * Don't forget to add an empty string as second argument to encode_base64 function to avoid a "​newline"​ characters insertion in result
 +  * Header names must contain only letters and "​-"​ character
 +</​note>​
 +
 +<note tip>By default, SSO cookie is hidden. So protected applications cannot retrieve SSO session key. But you can forward this key if absolutely needed:
 +<​code>​
 +Session-ID => $_session_id
 +</​code>​
 +</​note>​
 +
 +===== Available functions =====
 +
 +In addition to macros and name, you can use some functions in rules and headers:
 +  * [[extendedfunctions|LLNG extended functions]]
 +  * [[customfunctions|Your custom functions]]
 +
 +===== Wildcards in hostnames =====
 +
 +{{..:​new.png?​direct&​35|}} 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.
 +
 +Even if a wildcard exists, if a virtualhost is explicitly declared, this rule is applied. Example with precedence order:
 +  - test.sub.example.com
 +  - *.sub.example.com
 +  - test.example.com
 +  - *.example.com