312 lines
16 KiB
HTML
312 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>documentation:2.0:writingrulesand_headers</title>
|
|
<meta name="generator" content="DokuWiki"/>
|
|
<meta name="robots" content="index,follow"/>
|
|
<meta name="keywords" content="documentation,2.0,writingrulesand_headers"/>
|
|
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
|
|
<link rel="start" href="writingrulesand_headers.html"/>
|
|
<link rel="contents" href="writingrulesand_headers.html" title="Sitemap"/>
|
|
<link rel="stylesheet" type="text/css" href="lib/exe/css.php.t.bootstrap3.css"/>
|
|
<!-- //if:usedebianlibs
|
|
<link rel="stylesheet" type="text/css" href="/javascript/bootstrap/css/bootstrap.min.css" />
|
|
//elsif:useexternallibs
|
|
<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"></script>
|
|
//elsif:cssminified
|
|
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.min.css" />
|
|
//else -->
|
|
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.css" />
|
|
<!-- //endif -->
|
|
<script type="text/javascript">/*<![CDATA[*/var NS='documentation:2.0';var JSINFO = {"id":"documentation:2.0:writingrulesand_headers","namespace":"documentation:2.0"};
|
|
/*!]]>*/</script>
|
|
<script type="text/javascript" charset="utf-8" src="lib/exe/js.php.t.bootstrap3.js"></script>
|
|
<!-- //if:usedebianlibs
|
|
<script type="text/javascript" src="/javascript/jquery/jquery.min.js"></script>
|
|
//elsif:useexternallibs
|
|
<script type="text/javascript" src="http://code.jquery.com/jquery-2.2.0.min.js"></script>
|
|
//elsif:jsminified
|
|
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.min.js"></script>
|
|
//else -->
|
|
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.js"></script>
|
|
<!-- //endif -->
|
|
<!-- //if:usedebianlibs
|
|
<script type="text/javascript" src="/javascript/jquery-ui/jquery-ui.min.js"></script>
|
|
//elsif:useexternallibs
|
|
<script type="text/javascript" src="http://code.jquery.com/ui/1.10.4/jquery-ui.min.js"></script>
|
|
//elsif:jsminified
|
|
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.min.js"></script>
|
|
//else -->
|
|
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.js"></script>
|
|
<!-- //endif -->
|
|
</head>
|
|
<body>
|
|
<div class="dokuwiki export container">
|
|
<!-- TOC START -->
|
|
<div id="dw__toc">
|
|
<h3 class="toggle">Table of Contents</h3>
|
|
<div>
|
|
|
|
<ul class="toc">
|
|
<li class="level1"><div class="li"><a href="#available_env_variables">Available $ENV{} variables</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#rules">Rules</a></div>
|
|
<ul class="toc">
|
|
<li class="level2"><div class="li"><a href="#rules_on_authentication_level">Rules on authentication level</a></div></li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><div class="li"><a href="#headers">Headers</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#available_functions">Available functions</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#wildcards_in_hostnames">Wildcards in hostnames</a></div></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<!-- TOC END -->
|
|
|
|
<h1 class="sectionedit1" id="writing_rules_and_headers">Writing rules and headers</h1>
|
|
<div class="level1">
|
|
|
|
<p>
|
|
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,...).
|
|
</p>
|
|
<div class="noteimportant">Note that variables designed by $xx correspond to the name of the <a href="exportedvars.html" class="wikilink1" title="documentation:2.0:exportedvars">exported variables</a> or <a href="performances.html#macros_and_groups" class="wikilink1" title="documentation:2.0:performances">macro names</a> except for <code>$ENV{<cgi-header>}</code> which correspond to CGI header <em>(<code>$ENV{REMOTE_ADDR}</code> for example)</em>.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT1 SECTION "Writing rules and headers" [1-546] -->
|
|
<h2 class="sectionedit2" id="available_env_variables">Available $ENV{} variables</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
The %ENV table provides:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> all headers in CGI format <em>(<code>User-Agent</code> becomes <code>HTTP_USER_AGENT</code>)</em></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> some CGI variables depending on the context:</div>
|
|
<ul>
|
|
<li class="level2"><div class="li"> For portal: all CGI standard variables <em>(you can add custom headers using <code>fastcgi_param</code> with Nginx)</em>,</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> For Apache handler: REMOTE_ADDR, QUERY_STRING, REQUEST_<abbr title="Uniform Resource Identifier">URI</abbr>, SERVER_PORT, REQUEST_METHOD,</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> For Nginx handler: all variables given by <code>fastcgi_param</code> commands.</div>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><div class="li"> For portal:</div>
|
|
<ul>
|
|
<li class="level2"><div class="li"> $ENV{urldc} : Origin <abbr title="Uniform Resource Locator">URL</abbr> before Handler redirection, in cleartext</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> $ENV{_url} : Origin <abbr title="Uniform Resource Locator">URL</abbr> before Handler redirection, base64 encoded</div>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
See also <a href="extendedfunctions.html" class="wikilink1" title="documentation:2.0:extendedfunctions">extended functions</a>.
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT2 SECTION "Available $ENV{} variables" [547-1238] -->
|
|
<h2 class="sectionedit3" id="rules">Rules</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
A rule associates a <a href="http://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions" class="urlextern" title="http://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions" rel="nofollow">regular expression</a> to a Perl boolean expression or a keyword.
|
|
</p>
|
|
|
|
<p>
|
|
<a href="documentation/manager-rule.png_documentation_2.0_writingrulesand_headers.html" class="media" title="documentation:manager-rule.png"><img src="documentation/manager-rule.png" class="mediacenter" alt="" /></a>
|
|
</p>
|
|
|
|
<p>
|
|
Examples:
|
|
</p>
|
|
<div class="table sectionedit4"><table class="inline table table-bordered table-striped">
|
|
<thead>
|
|
<tr class="row0 roweven">
|
|
<th class="col0 centeralign"> Goal </th><th class="col1 centeralign"> Regular expression </th><th class="col2 centeralign"> Rule </th>
|
|
</tr>
|
|
</thead>
|
|
<tr class="row1 rowodd">
|
|
<td class="col0 leftalign"> Restrict /admin/ directory to user bart.simpson </td><td class="col1 centeralign"> ^/admin/ </td><td class="col2 centeralign"> $uid eq "bart.simpson" </td>
|
|
</tr>
|
|
<tr class="row2 roweven">
|
|
<td class="col0 leftalign"> Restrict /js/ and /css/ directory to authenticated users </td><td class="col1 centeralign"> ^/(css|js)/ </td><td class="col2 centeralign"> accept </td>
|
|
</tr>
|
|
<tr class="row3 rowodd">
|
|
<td class="col0 leftalign"> Deny access to /config/ directory </td><td class="col1 centeralign"> ^/config/ </td><td class="col2 centeralign"> deny </td>
|
|
</tr>
|
|
<tr class="row4 roweven">
|
|
<td class="col0 leftalign"> Do not restrict /public/ </td><td class="col1 centeralign"> ^/public/ </td><td class="col2 centeralign"> skip </td>
|
|
</tr>
|
|
<tr class="row5 rowodd">
|
|
<td class="col0 leftalign"> Makes authentication optional, but authenticated users are seen as such (that is, user data are sent to the app through HTTP headers) </td><td class="col1 centeralign"> ^/forum/ </td><td class="col2 centeralign"> unprotect </td>
|
|
</tr>
|
|
<tr class="row6 roweven">
|
|
<td class="col0 leftalign"> Restrict access to the whole site to users that have the LDAP description field set to "LDAP administrator" (must be set in exported variables) </td><td class="col1 centeralign"> default </td><td class="col2 centeralign"> $description eq "LDAP administrator" </td>
|
|
</tr>
|
|
</table></div>
|
|
<!-- EDIT4 TABLE [1461-2304] -->
|
|
<p>
|
|
The "<strong>default</strong>" access rule is used if no other access rule match the current <abbr title="Uniform Resource Locator">URL</abbr>.
|
|
</p>
|
|
<div class="notetip"><ul>
|
|
<li class="level1"><div class="li"> 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 <strong><a href="security.html#write_good_rules" class="wikilink1" title="documentation:2.0:security">security chapter</a></strong> to learn more about writing good rules.</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> See <a href="performances.html#handler_performance" class="wikilink1" title="documentation:2.0:performances">performances</a> to know how to use macros and groups in rules.</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<p>
|
|
Rules can also be used to intercept logout <abbr title="Uniform Resource Locator">URL</abbr>:
|
|
</p>
|
|
<div class="table sectionedit5"><table class="inline table table-bordered table-striped">
|
|
<thead>
|
|
<tr class="row0 roweven">
|
|
<th class="col0 centeralign"> Goal </th><th class="col1 centeralign"> Regular expression </th><th class="col2 centeralign"> Rule </th>
|
|
</tr>
|
|
</thead>
|
|
<tr class="row1 rowodd">
|
|
<td class="col0 leftalign"> Logout user from Lemonldap::NG and redirect it to http://intranet/ </td><td class="col1 centeralign"> ^/index.php\?logout </td><td class="col2 centeralign"> logout_sso http://intranet/ </td>
|
|
</tr>
|
|
<tr class="row2 roweven">
|
|
<td class="col0 leftalign"> Logout user from current application and redirect it to the menu <strong><em>(Apache only)</em></strong> </td><td class="col1 centeralign"> ^/index.php\?logout </td><td class="col2 centeralign"> logout_app https://auth.example.com/ </td>
|
|
</tr>
|
|
<tr class="row3 rowodd">
|
|
<td class="col0"> Logout user from current application and from Lemonldap::NG and redirect it to http://intranet/ <strong><em>(Apache only)</em></strong> </td><td class="col1 centeralign"> ^/index.php\?logout </td><td class="col2 centeralign"> logout_app_sso http://intranet/ </td>
|
|
</tr>
|
|
</table></div>
|
|
<!-- EDIT5 TABLE [2798-3446] --><div class="notewarning"><code>logout_app</code> and <code>logout_app_sso</code> rules are not available on Nginx, only on Apache.
|
|
</div>
|
|
<p>
|
|
By default, user will be redirected on portal if no <abbr title="Uniform Resource Locator">URL</abbr> defined, or on the specified <abbr title="Uniform Resource Locator">URL</abbr> if any.
|
|
</p>
|
|
<div class="noteimportant">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 <abbr title="HyperText Markup Language">HTML</abbr> page that explain that it is safe to close browser after disconnect.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT3 SECTION "Rules" [1239-3967] -->
|
|
<h3 class="sectionedit6" id="rules_on_authentication_level">Rules on authentication level</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
LLNG set an "authentication level" during authentication process. This level is the value of the authentication backend used for this user. Default values are:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> 0 for <a href="authnull.html" class="wikilink1" title="documentation:2.0:authnull">Null</a></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> 1 for <a href="authcas.html" class="wikilink1" title="documentation:2.0:authcas">CAS</a>, <a href="authopenid.html" class="wikilink1" title="documentation:2.0:authopenid">old OpenID-2</a>, <a href="authfacebook.html" class="wikilink1" title="documentation:2.0:authfacebook">Facebook</a>,…</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> 2 for web-form based authentication <em>(<a href="authldap.html" class="wikilink1" title="documentation:2.0:authldap">LDAP</a>, <a href="authdbi.html" class="wikilink1" title="documentation:2.0:authdbi">DBI</a>,…)</em></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> 3 for <a href="authyubikey.html" class="wikilink1" title="documentation:2.0:authyubikey">Yubikey</a></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> 4 for <a href="authapache.html" class="wikilink1" title="documentation:2.0:authapache">Kerberos</a></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> 5 for <a href="authssl.html" class="wikilink1" title="documentation:2.0:authssl">SSL</a></div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
There are two way to impose users to have a high authentication level:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> writing a rule based en authentication level: <code>$authenticationLevel > 3</code></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> since 2.0, set a minimum level in virtual host options</div>
|
|
</li>
|
|
</ul>
|
|
<div class="notetip">Instead of returning a 403 code, "minimum level" returns user to a form that explain that a higher level is required and propose the user to reauthenticate himself.
|
|
</div>
|
|
</div>
|
|
<!-- EDIT6 SECTION "Rules on authentication level" [3968-4855] -->
|
|
<h2 class="sectionedit7" id="headers">Headers</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Examples:
|
|
</p>
|
|
<div class="table sectionedit8"><table class="inline table table-bordered table-striped">
|
|
<thead>
|
|
<tr class="row0 roweven">
|
|
<th class="col0 centeralign"> Goal </th><th class="col1 centeralign"> Header name </th><th class="col2 centeralign"> Header value </th>
|
|
</tr>
|
|
</thead>
|
|
<tr class="row1 rowodd">
|
|
<td class="col0 leftalign"> Give the uid (for accounting) </td><td class="col1 centeralign"> Auth-User </td><td class="col2 centeralign"> $uid </td>
|
|
</tr>
|
|
<tr class="row2 roweven">
|
|
<td class="col0 leftalign"> Give a static value </td><td class="col1 centeralign"> Some-Thing </td><td class="col2 centeralign"> "static-value" </td>
|
|
</tr>
|
|
<tr class="row3 rowodd">
|
|
<td class="col0 leftalign"> Give display name </td><td class="col1 centeralign"> Display-Name </td><td class="col2 centeralign"> $givenName." ".$surName </td>
|
|
</tr>
|
|
<tr class="row4 roweven">
|
|
<td class="col0 leftalign"> Give a non ascii data </td><td class="col1 centeralign"> Display-Name </td><td class="col2 centeralign"> encode_base64($givenName." ".$surName,"") </td>
|
|
</tr>
|
|
</table></div>
|
|
<!-- EDIT8 TABLE [5039-5375] -->
|
|
<p>
|
|
As described in <a href="performances.html#handler_performance" class="wikilink1" title="documentation:2.0:performances">performances chapter</a>, you can use macros, local macros,...
|
|
</p>
|
|
<div class="noteimportant"><ul>
|
|
<li class="level1"><div class="li"> Since many HTTP servers refuse non ascii headers, it is recommended to use encode_base64() function to transmit those headers</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Don't forget to add an empty string as second argument to encode_base64 function to avoid a "newline" characters insertion in result</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Header names must contain only letters and "-" character</div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div><div class="notetip">By default, <abbr title="Single Sign On">SSO</abbr> cookie is hidden. So protected applications cannot retrieve <abbr title="Single Sign On">SSO</abbr> session key. But you can forward this key if absolutely needed:
|
|
<pre class="code">Session-ID => $_session_id</pre>
|
|
|
|
</div>
|
|
</div>
|
|
<!-- EDIT7 SECTION "Headers" [4856-6048] -->
|
|
<h2 class="sectionedit9" id="available_functions">Available functions</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
In addition to macros and name, you can use some functions in rules and headers:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> <a href="extendedfunctions.html" class="wikilink1" title="documentation:2.0:extendedfunctions">LLNG extended functions</a></div>
|
|
</li>
|
|
<li class="level1"><div class="li"> <a href="customfunctions.html" class="wikilink1" title="documentation:2.0:customfunctions">Your custom functions</a></div>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<!-- EDIT9 SECTION "Available functions" [6049-6259] -->
|
|
<h2 class="sectionedit10" id="wildcards_in_hostnames">Wildcards in hostnames</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
<a href="documentation/new.png" class="media" title="documentation:new.png"><img src="documentation/new.ae92cc06c5d7671f1d904a7fe6e5ed09.png" class="media" alt="" width="35" /></a> Since 2.0, a wildcard can be used in virtualhost name (not in aliases !): <code>*.example.com</code> matches all hostnames that belong to <code>example.com</code> domain.
|
|
</p>
|
|
|
|
<p>
|
|
Even if a wildcard exists, if a virtualhost is explicitly declared, this rule is applied. Example with precedence order:
|
|
</p>
|
|
<ol>
|
|
<li class="level1"><div class="li"> test.sub.example.com</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> *.sub.example.com</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> test.example.com</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> *.example.com</div>
|
|
</li>
|
|
</ol>
|
|
|
|
</div>
|
|
<!-- EDIT10 SECTION "Wildcards in hostnames" [6260-] --></div>
|
|
</body>
|
|
</html>
|