redirections.html 8.21 KB
Newer Older
Clément OUDOT's avatar
Clément OUDOT committed
1 2 3 4 5 6
<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
  <meta charset="utf-8" />
  <title>documentation:2.0:redirections</title>
<meta name="generator" content="DokuWiki"/>
Xavier Guimard's avatar
Xavier Guimard committed
7
<meta name="robots" content="index,follow"/>
Clément OUDOT's avatar
Clément OUDOT committed
8 9 10 11 12
<meta name="keywords" content="documentation,2.0,redirections"/>
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
<link rel="start" href="redirections.html"/>
<link rel="contents" href="redirections.html" title="Sitemap"/>
<link rel="stylesheet" type="text/css" href="lib/exe/css.php.t.bootstrap3.css"/>
Xavier Guimard's avatar
Xavier Guimard committed
13 14 15 16 17 18 19 20 21
<!-- //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 -->
Clément OUDOT's avatar
Clément OUDOT committed
22 23 24
<script type="text/javascript">/*<![CDATA[*/var NS='documentation:2.0';var JSINFO = {"id":"documentation:2.0:redirections","namespace":"documentation:2.0"};
/*!]]>*/</script>
<script type="text/javascript" charset="utf-8" src="lib/exe/js.php.t.bootstrap3.js"></script>
Xavier Guimard's avatar
Xavier Guimard committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38
<!-- //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
Xavier Guimard's avatar
Xavier Guimard committed
39
  <script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.min.js"></script>
Xavier Guimard's avatar
Xavier Guimard committed
40
//else -->
Xavier Guimard's avatar
Xavier Guimard committed
41
  <script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.js"></script>
Xavier Guimard's avatar
Xavier Guimard committed
42
<!-- //endif -->
Clément OUDOT's avatar
Clément OUDOT committed
43 44 45
</head>
<body>
<div class="dokuwiki export container">
Xavier Guimard's avatar
Xavier Guimard committed
46 47 48 49
<!-- TOC START -->
<div id="dw__toc">
<h3 class="toggle">Table of Contents</h3>
<div>
Clément OUDOT's avatar
Clément OUDOT committed
50

Xavier Guimard's avatar
Xavier Guimard committed
51 52 53 54 55 56 57 58 59 60 61 62 63 64
<ul class="toc">
<li class="level1"><div class="li"><a href="#handler_redirections">Handler Redirections</a></div>
<ul class="toc">
<li class="level2"><div class="li"><a href="#protocol_and_port">Protocol and port</a></div></li>
<li class="level2"><div class="li"><a href="#forbidden_and_server_error">Forbidden and Server error</a></div></li>
</ul>
</li>
<li class="level1"><div class="li"><a href="#portal_redirections">Portal Redirections</a></div></li>
</ul>
</div>
</div>
<!-- TOC END -->

<h1 class="sectionedit1" id="redirections">Redirections</h1>
Clément OUDOT's avatar
Clément OUDOT committed
65
<div class="level1">
Xavier Guimard's avatar
Xavier Guimard committed
66 67 68 69 70

</div>
<!-- EDIT1 SECTION "Redirections" [1-28] -->
<h2 class="sectionedit2" id="handler_redirections">Handler Redirections</h2>
<div class="level2">
Clément OUDOT's avatar
Clément OUDOT committed
71 72 73
<div class="noteclassic">When a user access a Handler without a cookie, he is redirected on portal, and the target <abbr title="Uniform Resource Locator">URL</abbr> is encoded in redirection <abbr title="Uniform Resource Locator">URL</abbr> (to redirect user after authentication process).
</div>
</div>
Xavier Guimard's avatar
Xavier Guimard committed
74 75 76
<!-- EDIT2 SECTION "Handler Redirections" [29-249] -->
<h3 class="sectionedit3" id="protocol_and_port">Protocol and port</h3>
<div class="level3">
Clément OUDOT's avatar
Clément OUDOT committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90

<p>
To encode the redirection <abbr title="Uniform Resource Locator">URL</abbr>, the handler will use some Apache environment variables and also configuration settings:
</p>
<ul>
<li class="level1"><div class="li"> <strong>HTTPS</strong>: use https as protocol</div>
</li>
<li class="level1"><div class="li"> <strong>Port</strong>: port of the application (by default, 80 for http, 443 for https)</div>
</li>
</ul>

<p>
These parameters can be configured in Manager, in <code>General Parameters</code> &gt; <code>Advanced parameters</code> &gt; <code>Handler redirections</code>.
</p>
Xavier Guimard's avatar
Xavier Guimard committed
91
<div class="notetip">These settings can be overridden per virtual host, see <a href="configvhost.html" class="wikilink1" title="documentation:2.0:configvhost">virtual host management</a>.
Clément OUDOT's avatar
Clément OUDOT committed
92 93
</div>
</div>
Xavier Guimard's avatar
Xavier Guimard committed
94 95 96
<!-- EDIT3 SECTION "Protocol and port" [250-756] -->
<h3 class="sectionedit4" id="forbidden_and_server_error">Forbidden and Server error</h3>
<div class="level3">
Clément OUDOT's avatar
Clément OUDOT committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140

<p>
Handler use the default Apache error code for the following cases:
</p>
<ul>
<li class="level1"><div class="li"> User has no access authorization: FORBIDDEN (403)</div>
</li>
<li class="level1"><div class="li"> An error occurs on server side: SERVER_ERROR (500)</div>
</li>
<li class="level1"><div class="li"> The application is in maintenance: HTTP_SERVICE_UNAVAILABLE (503)</div>
</li>
</ul>

<p>
These errors can be catch trough Apache <code>ErrorDocument</code> directive or Nginx <code>error_page</code> directive, to redirect user on a specific page:
</p>
<pre class="code file apache"><span class="co1"># Apache: Common error page and security parameters</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">403</span> http://auth.example.com/?lmError=<span class="nu0">403</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">500</span> http://auth.example.com/?lmError=<span class="nu0">500</span>
<span class="kw1">ErrorDocument</span> <span class="nu0">503</span> http://auth.example.com/?lmError=<span class="nu0">503</span></pre>
<pre class="code file nginx"># Nginx: Common error page and security parameters
error_page 403 http://auth.example.com/?lmError=403;
error_page 500 http://auth.example.com/?lmError=500;
error_page 503 http://auth.example.com/?lmError=503;</pre>

<p>
It is also possible to redirect the user without using <code>ErrorDocument</code>: the Handler will not returnV 403, 500, 503 code, but code 302 (REDIRECT). 
</p>

<p>
The user will be redirected on portal <abbr title="Uniform Resource Locator">URL</abbr> with error in the <code>lmError</code> <abbr title="Uniform Resource Locator">URL</abbr> parameter.
</p>

<p>
These parameters can be configured in Manager, in <code>General Parameters</code> &gt; <code>Advanced parameters</code> &gt; <code>Handler redirections</code>:
</p>
<ul>
<li class="level1"><div class="li"> <strong>Redirect on forbidden</strong>: use 302 instead 403</div>
</li>
<li class="level1"><div class="li"> <strong>Redirect on error</strong>: use 302 instead 500 or 503</div>
</li>
</ul>

</div>
Xavier Guimard's avatar
Xavier Guimard committed
141 142 143
<!-- EDIT4 SECTION "Forbidden and Server error" [757-2126] -->
<h2 class="sectionedit5" id="portal_redirections">Portal Redirections</h2>
<div class="level2">
Clément OUDOT's avatar
Clément OUDOT committed
144 145 146 147 148 149
<div class="noteclassic">If a user is redirected from handler to portal for authentication and once he is authenticated, portal redirects him to the redirection <abbr title="Uniform Resource Locator">URL</abbr>.
</div><ul>
<li class="level1"><div class="li"> <strong>Redirection message</strong>:  The redirection from portal can be done either with code 303 (See Other), or with a JavaScript redirection. Often the redirection takes some time because it is user&#039;s first access to the protected app, so a new app session has to be created : JavaScript redirection improves user experience by informing that authentication is performed, and by preventing from clicking again on the button because it is too slow.</div>
</li>
<li class="level1"><div class="li"> <strong>Keep redirections for Ajax</strong>: By default, when an Ajax request is done on the portal for an unauthenticated user (after a redirection done by the handler), a 401 code will be sentwith a <code>WWW-Authenticate</code> header containing “<abbr title="Single Sign On">SSO</abbr> &lt;portal-<abbr title="Uniform Resource Locator">URL</abbr>&gt;”. Set this option to 1 to keep the old behavior (return of <abbr title="HyperText Markup Language">HTML</abbr> code).</div>
</li>
Xavier Guimard's avatar
Xavier Guimard committed
150 151
<li class="level1"><div class="li"> <strong>Skip re-auth confirmation</strong>: by default, when re-authentication is needed, a confirmation screen is displayed to let user accept the re-authentication. If you enable this option, user will be directly redirected to login page.</div>
</li>
Clément OUDOT's avatar
Clément OUDOT committed
152 153 154
</ul>

</div>
Xavier Guimard's avatar
Xavier Guimard committed
155
<!-- EDIT5 SECTION "Portal Redirections" [2127-] --></div>
Clément OUDOT's avatar
Clément OUDOT committed
156 157
</body>
</html>