# 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 that variables designed by $xx correspond to the name of the exported variables or macro names.

## Rules

A rule associates a regular expression to a Perl boolean expression or a keyword.

Examples:

Goal | Regular expression | Rule
--- | --- | ---
Restrict /admin/ directory to user bart.simpson | ^/admin/ | $uid eq "bart.simpson"
Restrict /js/ and /css/ directory to authenticated users | ^/(css|js)/ | accept
Deny access to /config/ directory | ^/config/ | deny
Do not restrict /public/ | ^/public/ | skip
Makes authentication optional, but authenticated users are seen as such (that is, user data are sent to the app through HTTP headers) | ^/forum/ | 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 | $description eq "LDAP administrator"

The “default” access rule is used if no other access rule match the current URL.

- 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 chapter to learn more about writing good rules.
- See performances to know how to use macros and groups in rules.

Rules can also be used to intercept logout URL:

Goal | Regular expression | Rule
--- | --- | ---
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 | ^/index.php\?logout | logout_app https://auth.example.com/
Logout user from current application and from Lemonldap::NG and redirect it to http://intranet/ | ^/index.php\?logout | logout_app_sso http://intranet/

`logout_app` and `logout_app_sso` rules are not available on Nginx, only on Apache.
By default, user will be redirected on portal if no URL defined, or on the specified URL if any.
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.

## 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 | encode_base64($givenName." ".$surName, '')

As described in performances chapter, you can use macros, local macros,…

- 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 of encode_base64 to avoid insert of “newline” characters in result
- Header names must contain only letters and “-” character

By default, SSO cookie is hidden, so protected applications cannot get SSO session key. But you can forward this key if it is really needed:

    Session-ID => $_session_id