Writing rules and headers¶

LL::NG manages applications by their hostname (Apache Virtual Hosts or Nginx Block Servers). Rules are used for protecting applications, and HTTP headers are appended to each request for sending data to protected applications (for logs, profiles,…).

Attention

Note that variables designed by $xx correspond to the name of the exported variables or macro names except for $ENV{<cgi-header>} which correspond to CGI headers ($ENV{REMOTE_ADDR} for example).

Available $ENV variables¶

The %ENV hash 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

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/
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
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

The “default” access rule is used if none rule matches the current URL.

Tip

See the rule examples page for few common use cases

Tip

Comments can be employed for ordering your rules: rules are applied depending on comment alphabetical order (or regexp if no comment is defined). See security chapter to learn more about rules best practice.
See performances to learn how using macros and groups in rules.

Rules can also be used for intercepting 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 (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/

Danger

logout_app and logout_app_sso rules are not available with Nginx, Apache ONLY.

By default, users will be redirected to the Portal if no URL is defined, or to the specified URL if exists.

Attention

Only current application is concerned by logout_app* 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.

Rules based on authentication level¶

LL::NG set an “authentication level” during authentication process. This level depends on authentication backend used by this user. Default values are:

0 for Null
1 for CAS, OpenID Connect, Facebook,…
2 for web-form based authentication (LDAP, DBI,…)
3 for Kerberos
5 for SSL

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).

Tip

Instead of returning a 403 code, “minimum level” returns users to a form that explains that a higher level is required and propose to reauthenticate himself.

Headers¶

Headers are associations between an header name and a perl expression that returns a value. Headers are used for sending user data to protected applications.

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

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

Attention

Since many HTTP servers refuse non ASCII headers, it is recommended to use encode_base64() function to transmit those headers
Do not forget to add an empty string as second argument to encode_base64 function to avoid a “newline” characters insertion in result: encode_base64($string, '')
Header names must contain only letters and “-” character. With Nginx, you can bypass this restriction by using underscores_in_headers on; directive

Tip

By default, SSO cookie is hidden. So protected applications cannot retrieve SSO session key. But you can forward this key if absolutely needed (NOT recommanded because can be a security issue):

Session-ID => $_session_id

Available functions¶

In addition to macros and name, you can use some functions in rules and headers:

Wildcards in hostnames¶

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.

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:

test.sub.example.com
test%.sub.example.com
test*.sub.example.com
%.sub.example.com
*.sub.example.com
*.example.com (%.example.com does not match test.sub.example.com)