lemonldap-ng/doc/pages/documentation/current/portalcustom.html
2020-05-05 15:40:05 +02:00

474 lines
22 KiB
HTML

<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
<meta charset="utf-8" />
<title>documentation:2.0:portalcustom</title>
<meta name="generator" content="DokuWiki"/>
<meta name="robots" content="index,follow"/>
<meta name="keywords" content="documentation,2.0,portalcustom"/>
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
<link rel="start" href="portalcustom.html"/>
<link rel="contents" href="portalcustom.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:portalcustom","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="level2"><div class="li"><a href="#main_logo">Main Logo</a></div></li>
<li class="level2"><div class="li"><a href="#show_languages_choice">Show languages choice</a></div></li>
<li class="level2"><div class="li"><a href="#custom_css_file">Custom CSS file</a></div></li>
<li class="level1"><div class="li"><a href="#skin">Skin</a></div></li>
<li class="level2"><div class="li"><a href="#default_skin">Default skin</a></div></li>
<li class="level2"><div class="li"><a href="#skin_background">Skin background</a></div></li>
<li class="level2"><div class="li"><a href="#skin_rules">Skin rules</a></div></li>
<li class="level2"><div class="li"><a href="#skin_files">Skin files</a></div></li>
<li class="level2"><div class="li"><a href="#skin_customization">Skin customization</a></div></li>
<li class="level2"><div class="li"><a href="#messages">Messages</a></div></li>
<li class="level2"><div class="li"><a href="#menu_tabs">Menu tabs</a></div></li>
<li class="level2"><div class="li"><a href="#template_parameters">Template parameters</a></div></li>
<li class="level1"><div class="li"><a href="#buttons">Buttons</a></div></li>
<li class="level1"><div class="li"><a href="#password_management">Password management</a></div></li>
<li class="level2"><div class="li"><a href="#general">General</a></div></li>
<li class="level2"><div class="li"><a href="#password_policy">Password Policy</a></div></li>
<li class="level1"><div class="li"><a href="#other_parameters">Other parameters</a></div></li>
</ul>
</div>
</div>
<!-- TOC END -->
<h1 class="sectionedit1" id="portal_customization">Portal customization</h1>
<div class="level1">
<div class="noteclassic">The portal is the visible part of LemonLDAP::NG, all user interactions are displayed on it.
</div>
</div>
<!-- EDIT1 SECTION "Portal customization" [1-142] -->
<h3 class="sectionedit2" id="main_logo">Main Logo</h3>
<div class="level3">
<p>
You can change the default Main Logo in Manager: General Parameters &gt; Portal &gt; Customization &gt; Main Logo.
</p>
<p>
A blank value disables Main Logo display.
</p>
<div class="notetip">- Logo files must be stored in lemonldap-ng-portal/site/htdocs/static/my/path directory
<p>
- Logo file path must be like my/path/logo.png
</p>
<p>
- Main logo is included in Portal templates AND mail body
</p>
</div>
</div>
<!-- EDIT2 SECTION "Main Logo" [143-528] -->
<h3 class="sectionedit3" id="show_languages_choice">Show languages choice</h3>
<div class="level3">
<p>
You can disabled languages choice in Manager: General Parameters &gt; Portal &gt; Customization &gt; Show languages choice.
</p>
<p>
Option enabled by default.
</p>
<div class="notetip">If languages choice is disabled, Portal displays accepted languages by your browser (EN by default).
</div>
</div>
<!-- EDIT3 SECTION "Show languages choice" [529-828] -->
<h3 class="sectionedit4" id="custom_css_file">Custom CSS file</h3>
<div class="level3">
<p>
You can define a custom <abbr title="Cascading Style Sheets">CSS</abbr> file, for example <code>custom.css</code>, which will be loaded after default <abbr title="Cascading Style Sheets">CSS</abbr> files. This file needs to be created in the static repository (<code>/usr/share/lemonldap-ng/portal/htdocs/static/boostrap/css</code>).
</p>
<p>
Then set this value in Custom <abbr title="Cascading Style Sheets">CSS</abbr> parameter : <code>bootstrap/css/custom.css</code>.
</p>
<p>
Sample <abbr title="Cascading Style Sheets">CSS</abbr> file, to remove white background of main logo:
</p>
<pre class="code file css"><span class="re0">#header</span> img <span class="br0">&#123;</span>
<span class="kw1">background-color</span><span class="sy0">:</span> <span class="kw2">transparent</span><span class="sy0">;</span>
<span class="br0">&#125;</span></pre>
</div>
<!-- EDIT4 SECTION "Custom CSS file" [829-1288] -->
<h2 class="sectionedit5" id="skin">Skin</h2>
<div class="level2">
<p>
LemonLDAP::NG is shipped with bootstrap skin.
</p>
<p>
But you can make your own. See Skin customization below.
</p>
</div>
<!-- EDIT5 SECTION "Skin" [1289-1411] -->
<h3 class="sectionedit6" id="default_skin">Default skin</h3>
<div class="level3">
<p>
You can change the default skin in Manager: <code>General Parameters</code> &gt; <code>Portal</code> &gt; <code>Customization</code> &gt; <code>Default skin</code>.
</p>
<p>
Select the <code>Custom</code> skin, then set the name of the skin you want to use in the input below.
</p>
</div>
<!-- EDIT6 SECTION "Default skin" [1412-1651] -->
<h3 class="sectionedit7" id="skin_background">Skin background</h3>
<div class="level3">
<p>
Go in <code>General Parameters</code> &gt; <code>Portal</code> &gt; <code>Customization</code> &gt; <code>Skin background</code>. You can define a background by selecting one of the available image. Use <code>None</code> to use the default skin background configuration.
</p>
<p>
<img src="documentation/manager-skin-background.png" class="mediacenter" alt="" />
</p>
<p>
To set your own background, copy your file in <code>/usr/share/lemonldap-ng/portal/htdocs/skins/common/backgrounds/</code> and register it in <code>/etc/lemonldap-ng/lemonldap-ng.ini</code>:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>portal<span class="br0">&#93;</span></span>
<span class="re1">portalSkinBackground</span> <span class="sy0">=</span><span class="re2"> file.png</span></pre>
<p>
You can also use <code>lemonldap-ng-cli</code>:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli set portalSkinBackground file.png</pre>
</div>
<!-- EDIT7 SECTION "Skin background" [1652-2321] -->
<h3 class="sectionedit8" id="skin_rules">Skin rules</h3>
<div class="level3">
<p>
You might want to display different skin depending on the <abbr title="Uniform Resource Locator">URL</abbr> that was called before being redirected to the portal, or the <abbr title="Internet Protocol">IP</abbr> address of the user.
</p>
<p>
To achieve this, you can create a rule in the Manager: select <code>General Parameters</code> &gt; <code>Portal</code> &gt; <code>Customization</code> &gt; <code>Skin display rules</code> on click on &quot;New key&quot;. Then fill the two fields;
</p>
<ul>
<li class="level1"><div class="li"> <strong>Rule</strong>: a Perl expression (you can use %ENV hash to get environment variables, or $_url to get <abbr title="Uniform Resource Locator">URL</abbr> called before redirection, or $ipAddr to use user <abbr title="Internet Protocol">IP</abbr> address). If the rule evaluation is true, the corresponding skin is applied.</div>
</li>
<li class="level1"><div class="li"> <strong>Skin</strong>: the name of the skin to use.</div>
</li>
</ul>
</div>
<!-- EDIT8 SECTION "Skin rules" [2322-2964] -->
<h3 class="sectionedit9" id="skin_files">Skin files</h3>
<div class="level3">
<p>
A skin is composed of different files:
</p>
<ul>
<li class="level1"><div class="li"> <strong>.tpl</strong>: Perl <abbr title="HyperText Markup Language">HTML</abbr>::Template files, for <abbr title="HyperText Markup Language">HTML</abbr> content</div>
</li>
<li class="level1"><div class="li"> <strong>.css</strong>: <abbr title="Cascading Style Sheets">CSS</abbr> (styles)</div>
</li>
<li class="level1"><div class="li"> <strong>.js</strong>: Javascript</div>
</li>
<li class="level1"><div class="li"> images and other media files</div>
</li>
</ul>
<p>
A skin will often refer to the <code>common</code> skin, which is not a real skin, but shared skin objects (like scripts, images and <abbr title="Cascading Style Sheets">CSS</abbr>).
</p>
</div>
<!-- EDIT9 SECTION "Skin files" [2965-3299] -->
<h3 class="sectionedit10" id="skin_customization">Skin customization</h3>
<div class="level3">
<div class="noteimportant">If you modify directly the skin files, your modifications will certainly be erased on the next upgrade. The best is to create your own skin, based on an existing skin.
</div>
<p>
Here we explain how to create a new skin, named <code>myskin</code>, from the <code>bootstrap</code> skin.
</p>
<p>
First copy static content:
</p>
<pre class="code">cd /usr/share/lemonldap-ng/portal/htdocs/static
mkdir myskin
cd myskin/
cp -a ../bootstrap/js/ .
cp -a ../bootstrap/css/ .
mkdir images</pre>
<p>
Then create symbolic links on template files, as you might not want to rewrite all <abbr title="HyperText Markup Language">HTML</abbr> code (else, do as you want).
</p>
<pre class="code">cd /usr/share/lemonldap-ng/portal/templates/
mkdir myskin
cd myskin/</pre>
<p>
We include some template files that can be customized:
</p>
<ul>
<li class="level1"><div class="li"> customhead.tpl : <abbr title="HyperText Markup Language">HTML</abbr> header markups (like <abbr title="Cascading Style Sheets">CSS</abbr>, js inclusion)</div>
</li>
<li class="level1"><div class="li"> customheader.tpl : <abbr title="HyperText Markup Language">HTML</abbr> code in the header</div>
</li>
<li class="level1"><div class="li"> customfooter.tpm : <abbr title="HyperText Markup Language">HTML</abbr> code in the footer</div>
</li>
<li class="level1"><div class="li"> customLoginHeader.tpl : <abbr title="HyperText Markup Language">HTML</abbr> code int the login header</div>
</li>
<li class="level1"><div class="li"> customLoginFooter.tpl : <abbr title="HyperText Markup Language">HTML</abbr> code int the login footer</div>
</li>
</ul>
<p>
To use custom files, copy them into your skin folder:
</p>
<pre class="code">cp ../bootstrap/custom* .</pre>
<p>
Then you can add your media to <code>myskin/images</code>, you will be able to use them in <abbr title="HyperText Markup Language">HTML</abbr> template with this code:
</p>
<pre class="code">&lt;img src=&quot;&lt;TMPL_VAR NAME=&quot;STATIC_PREFIX&quot;&gt;myskin/images/logo.png&quot; class=&quot;mx-auto d-block&quot; /&gt;</pre>
<p>
To change <abbr title="Cascading Style Sheets">CSS</abbr>, two options:
</p>
<ul>
<li class="level1"><div class="li"> Edit myksin/css/styles.css and myskin/css/styles.min.css</div>
</li>
<li class="level1"><div class="li"> Create a new <abbr title="Cascading Style Sheets">CSS</abbr> file, for example myskin/css/myskin.css and load it in customhead.tpl:</div>
</li>
</ul>
<pre class="code">&lt;link href=&quot;&lt;TMPL_VAR NAME=&quot;STATIC_PREFIX&quot;&gt;myskin/css/myskin.css&quot; rel=&quot;stylesheet&quot; type=&quot;text/css&quot; /&gt;</pre>
<p>
Put then all custom <abbr title="HyperText Markup Language">HTML</abbr> code in the custom template files.
</p>
<p>
To configure your new skin in Manager, select the custom skin, and enter your skin name in the configuration field. For example with lemonldap-ng-cli:
</p>
<pre class="code">/usr/share/lemonldap-ng/bin/lemonldap-ng-cli -yes 1 set portalSkin &#039;myskin&#039; portalSkinBackground &#039;&#039;</pre>
</div>
<!-- EDIT10 SECTION "Skin customization" [3300-5269] -->
<h3 class="sectionedit11" id="messages">Messages</h3>
<div class="level3">
<p>
Messages are defined in source code. If they really do not please you, override them! You just need to know the ID of the message (look at Portal/Simple.pm).
</p>
<p>
There are two methods to do this:
</p>
<ul>
<li class="level1"><div class="li"> Use <code>lemonldap-ng.ini</code>:</div>
</li>
</ul>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>portal<span class="br0">&#93;</span></span>
&nbsp;
# Custom error messages
<span class="re1">error_0</span> <span class="sy0">=</span><span class="re2"> Big brother is watching you, authenticated user</span>
&nbsp;
# Custom standard messages
<span class="re1">msg_lastLogins</span> <span class="sy0">=</span><span class="re2"> Your last connections</span></pre>
<p>
You can also define messages in several languages or disable message boxes by using the bareword <code>_hide_</code> :
</p>
<pre class="code file ini"><span class="re1">error_en_0</span> <span class="sy0">=</span><span class="re2"> Big brother is watching you, authenticated user</span>
<span class="re1">error_fr_0</span> <span class="sy0">=</span><span class="re2"> Souriez vous êtes surveillés !</span>
<span class="re1">msg_fr_lastLogins</span> <span class="sy0">=</span><span class="re2"> Dernières connexions</span>
<span class="re1">error_9</span> <span class="sy0">=</span><span class="re2"> _hide_</span></pre>
<ul>
<li class="level1"><div class="li"> Create a lang file in custom skin:</div>
</li>
</ul>
<p>
If you have a custom skin, then you can create a lang file in <code>templates/&lt;your skin&gt;</code> similar to the default lang files provided in <code>htdocs/static/languages/</code>.
</p>
<p>
For example <code>templates/myskin/en.json</code>:
</p>
<pre class="code file javascript"><span class="br0">&#123;</span>
<span class="st0">&quot;PE9&quot;</span><span class="sy0">:</span><span class="st0">&quot;Please authenticate!&quot;</span>
<span class="br0">&#125;</span></pre>
<p>
You can also create a file called <code>all.json</code> to override messages in all languages.
</p>
</div>
<!-- EDIT11 SECTION "Messages" [5270-6406] -->
<h3 class="sectionedit12" id="menu_tabs">Menu tabs</h3>
<div class="level3">
<p>
If you modify the menu template to add some tabs, you should add the new tabs in `customMenuTabs` parameter in lemonldap-ng.ini:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>portal<span class="br0">&#93;</span></span>
&nbsp;
<span class="re1">customMenuTabs</span> <span class="sy0">=</span><span class="re2"> test, test2</span></pre>
<p>
This will allow one to display the tab directly with this <abbr title="Uniform Resource Locator">URL</abbr>: <a href="http://auth.example.com/?tab=test" class="urlextern" title="http://auth.example.com/?tab=test" rel="nofollow">http://auth.example.com/?tab=test</a>
</p>
</div>
<!-- EDIT12 SECTION "Menu tabs" [6407-6713] -->
<h3 class="sectionedit13" id="template_parameters">Template parameters</h3>
<div class="level3">
<p>
Template parameters are defined in source code. If you need to add a template parameter for your customization, then add to <code>lemonldap-ng.ini</code>:
</p>
<pre class="code file ini"><span class="re0"><span class="br0">&#91;</span>portal<span class="br0">&#93;</span></span>
&nbsp;
# Custom template parameters
<span class="re1">tpl_myparam</span> <span class="sy0">=</span><span class="re2"> world</span></pre>
<p>
Then you will be able to use it in your template like this:
</p>
<pre class="code file html4strict">Hello <span class="sc2">&lt;TMPL_VAR <span class="kw3">NAME</span><span class="sy0">=</span><span class="st0">&quot;myparam&quot;</span>&gt;</span>!</pre>
<p>
All session variables are also available in templates, with the prefix <code>session_</code>:
</p>
<pre class="code file html4strict">Hello <span class="sc2">&lt;TMPL_VAR <span class="kw3">NAME</span><span class="sy0">=</span><span class="st0">&quot;session_cn&quot;</span>&gt;</span>!</pre>
<p>
You can also display environment variables, with the prefix <code>env_</code>:
</p>
<pre class="code file html4strict">Your IP is <span class="sc2">&lt;TMPL_VAR <span class="kw3">NAME</span><span class="sy0">=</span><span class="st0">&quot;env_REMOTE_ADDR&quot;</span>&gt;</span></pre>
</div>
<!-- EDIT13 SECTION "Template parameters" [6714-7361] -->
<h2 class="sectionedit14" id="buttons">Buttons</h2>
<div class="level2">
<p>
This node allows one to enable/disable buttons on the login page:
</p>
<ul>
<li class="level1"><div class="li"> <strong>Check last logins</strong>: displays a checkbox on login form, allowing user to check his login history right after opening session</div>
</li>
<li class="level1"><div class="li"> <strong>Reset password</strong>: display a link to <a href="resetpassword.html" class="wikilink1" title="documentation:2.0:resetpassword">reset your password page</a> (for password based authentication backends). Number of allowed retries can be set (3 times by default)</div>
</li>
<li class="level1"><div class="li"> <strong>Register</strong>: display a link to <a href="register.html" class="wikilink1" title="documentation:2.0:register">register page</a> (for password based authentication backends)</div>
</li>
</ul>
</div>
<!-- EDIT14 SECTION "Buttons" [7362-7878] -->
<h2 class="sectionedit15" id="password_management">Password management</h2>
<div class="level2">
</div>
<!-- EDIT15 SECTION "Password management" [7879-7911] -->
<h3 class="sectionedit16" id="general">General</h3>
<div class="level3">
<ul>
<li class="level1"><div class="li"> <strong>Require old password</strong>: used only in the password changing module of the menu, will check the old password before updating it</div>
</li>
<li class="level1"><div class="li"> <strong>Hide old password</strong>: used only if the password need to be reset by the user (LDAP password policy), will hide the old password input</div>
</li>
<li class="level1"><div class="li"> <strong>Send mail on password change</strong>: send a mail if the password is changed from the Menu, or from forced password reset (LDAP password policy)</div>
</li>
</ul>
</div>
<!-- EDIT16 SECTION "General" [7912-8347] -->
<h3 class="sectionedit17" id="password_policy">Password Policy</h3>
<div class="level3">
<div class="notetip">Available since version 2.0.6
</div><ul>
<li class="level1"><div class="li"> <strong>Minimal size</strong>: leave 0 to bypass the check</div>
</li>
<li class="level1"><div class="li"> <strong>Minimal lower characters</strong>: leave 0 to bypass the check</div>
</li>
<li class="level1"><div class="li"> <strong>Minimal upper characters</strong>: leave 0 to bypass the check</div>
</li>
<li class="level1"><div class="li"> <strong>Minimal digit characters</strong>: leave 0 to bypass the check</div>
</li>
<li class="level1"><div class="li"> <strong>Minimal special characters</strong>: leave 0 to bypass the check</div>
</li>
<li class="level1"><div class="li"> <strong>Allowed special characters</strong>: set blanck to forbid special characters (<code>_</code> is not a special character)</div>
</li>
<li class="level1"><div class="li"> <strong>Display policy in password form</strong>: enable this to display an information message about password policy constraints</div>
</li>
</ul>
</div>
<!-- EDIT17 SECTION "Password Policy" [8348-8955] -->
<h2 class="sectionedit18" id="other_parameters">Other parameters</h2>
<div class="level2">
<ul>
<li class="level1"><div class="li"> <strong>User attribute</strong>: which session attribute will be used to display <code>Connected as</code> in the menu</div>
</li>
<li class="level1"><div class="li"> <strong>New window</strong>: open menu links in new window</div>
</li>
<li class="level1"><div class="li"> <strong>Anti iframe protection</strong>: Set <code>X-Frame-Options</code> and CSP <code>frame-ancestors</code> headers (see <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#Browser_compatibility" class="urlextern" title="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#Browser_compatibility" rel="nofollow">Browser compatibility</a>)</div>
</li>
<li class="level1"><div class="li"> <strong>Ping interval</strong>: Number of milliseconds between each ping (Ajax request) on the portal menu. Set to 0 to dismiss checks.</div>
</li>
<li class="level1"><div class="li"> <strong>Show error on expired session</strong>: Display the error &quot;Session expired&quot;, which stops the authentication process. This is enabled by default but can be disabled to prevent transparent authentication (like SSL or Kerberos) to be stopped.</div>
</li>
<li class="level1"><div class="li"> <strong>Show error on mail not found</strong>: Display error if provided mail is not found in password reset by mail process. Disabled by default to prevent mail enumeration from this page.</div>
</li>
</ul>
</div>
<!-- EDIT18 SECTION "Other parameters" [8956-] --></div>
</body>
</html>