300 lines
14 KiB
HTML
300 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" dir="ltr">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<title>documentation:2.0:applications:humhub</title>
|
|
<meta name="generator" content="DokuWiki"/>
|
|
<meta name="robots" content="index,follow"/>
|
|
<meta name="keywords" content="documentation,2.0,applications,humhub"/>
|
|
<link rel="search" type="application/opensearchdescription+xml" href="../lib/exe/opensearch.html" title="LemonLDAP::NG"/>
|
|
<link rel="start" href="humhub.html"/>
|
|
<link rel="contents" href="humhub.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:applications';var JSINFO = {"id":"documentation:2.0:applications:humhub","namespace":"documentation:2.0:applications"};
|
|
/*!]]>*/</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="#presentation">Présentation</a></div></li>
|
|
<li class="level1"><div class="li"><a href="#openid_connect">OpenID Connect</a></div>
|
|
<ul class="toc">
|
|
<li class="level2"><div class="li"><a href="#configuring_humhub">Configuring HumHub</a></div></li>
|
|
<li class="level2"><div class="li"><a href="#configuring_lemonldap">Configuring LemonLDAP</a></div></li>
|
|
<li class="level2"><div class="li"><a href="#migrate_former_local_or_ldap_humhub_account_to_connect_through_sso">Migrate former local or ldap Humhub account to connect through SSO</a></div></li>
|
|
<li class="level2"><div class="li"><a href="#troubleshooting">Troubleshooting</a></div></li>
|
|
</ul></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<!-- TOC END -->
|
|
|
|
<h1 class="sectionedit1" id="humhub">HumHub</h1>
|
|
<div class="level1">
|
|
|
|
<p>
|
|
<img src="humhub_logo.png" class="mediacenter" alt="" />
|
|
</p>
|
|
|
|
</div>
|
|
<!-- EDIT1 SECTION "HumHub" [1-67] -->
|
|
<h2 class="sectionedit2" id="presentation">Présentation</h2>
|
|
<div class="level2">
|
|
|
|
<p>
|
|
<a href="https://humhub.org/" class="urlextern" title="https://humhub.org/" rel="nofollow">HumHub</a> is a free and open-source social network written on top of the <a href="https://www.yiiframework.com/" class="urlextern" title="https://www.yiiframework.com/" rel="nofollow">Yii2 PHP framework</a> that provides an easy to use toolkit for creating and launching your own social network.
|
|
</p>
|
|
|
|
<p>
|
|
Unauthenticated users may connect using a login form against HumHub local database or a LDAP directory, or choose which authentication service they want to use.
|
|
</p>
|
|
|
|
<p>
|
|
Administrator can configure one or several OAuth, OAuth2 or OIDC authentication services to be displayed as buttons on the login page.
|
|
</p>
|
|
|
|
<p>
|
|
With <a href="#openid_connect" title="documentation:2.0:applications:humhub ↵" class="wikilink1"> OpenID Connect </a> authentication service, users successfully authenticated by LemonLDAP::NG will be registered in HumHub upon their first login.
|
|
</p>
|
|
<div class="notewarning">HumHub retrieves a user from his username and the authentication service he came through. As a result, a former local or LDAP user will be rejected when trying to authenticate using another authentication service. See <a href="#migrate_former_local_or_ldap_humhub_account_to_connect_through_sso" title="documentation:2.0:applications:humhub ↵" class="wikilink1"> Migrate former local or ldap Humhub account to connect through SSO</a>
|
|
|
|
</div>
|
|
</div>
|
|
<!-- EDIT2 SECTION "Présentation" [68-1186] -->
|
|
<h2 class="sectionedit3" id="openid_connect">OpenID Connect</h2>
|
|
<div class="level2">
|
|
<div class="noteclassic">This set-up works with option enablePrettyUrl activated in Humhub. If not activated, rewrite <abbr title="Uniform Resource Locator">URL</abbr> in Humhub HTTP server and allowed redirect <abbr title="Uniform Resource Locator">URL</abbr> in LemonLDAP needs to be adapted to work with the non pretty <abbr title="Uniform Resource Locator">URL</abbr> format.
|
|
|
|
</div>
|
|
</div>
|
|
<!-- EDIT3 SECTION "OpenID Connect" [1187-1450] -->
|
|
<h3 class="sectionedit4" id="configuring_humhub">Configuring HumHub</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
First disable LDAP (Administration > Users section) and delete (or <a href="#migrate_former_local_or_ldap_humhub_account_to_connect_through_sso" title="documentation:2.0:applications:humhub ↵" class="wikilink1"> migrate</a>) any local users whose username or email are conflicting with the username or email of your OIDC users.
|
|
</p>
|
|
|
|
<p>
|
|
Then install and configure the <a href="https://github.com/Worteks/humhub-auth-oidc" class="urlextern" title="https://github.com/Worteks/humhub-auth-oidc" rel="nofollow"> OIDC connector for humhub </a> extension using composer :
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Install composer.</div>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Consider using prestissimo, to speed up composer update command (4x faster):</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">composer global require hirak/prestissimo</pre>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Go to {humhub_home} folder</div>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Check if composer.json file is present. If not, download it for your current version:</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">wget https://raw.githubusercontent.com/humhub/humhub/v1.3.15/composer.json</pre>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Install the connector as a dependency: </div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">composer require --no-update --update-no-dev worteks/humhub-auth-oidc
|
|
composer update worteks/humhub-auth-oidc --no-dev --prefer-dist -vvv</pre>
|
|
<div class="noteclassic">If you just need to update the connector, change its version in composer.json and run the above composer update command.
|
|
|
|
</div><ul>
|
|
<li class="level1"><div class="li"> Edit {humhub_home}/protected/config/common.php with the client configuration :</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">'components' => [
|
|
'authClientCollection' => [
|
|
'clients' => [
|
|
// ...
|
|
'lemonldapng' => [
|
|
'class' => 'worteks\humhub\authclient\OIDC',
|
|
'domain' => 'https://auth.example.com',
|
|
'clientId' => 'myClientId', // Client ID for this RP in LemonLDAP
|
|
'clientSecret' => 'myClientSecret', // Client secret for this RP in LemonLDAP
|
|
'defaultTitle' => 'auth.example.com', // Text displayed in login button
|
|
'cssIcon' => 'fa fa-lemon-o', // Icon displayed in login button
|
|
],
|
|
],
|
|
// ...
|
|
]</pre>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Edit {humhub_home}/protected/config/web.php to disconnect users from LemonLDAP::NG after they logged out of Humhub:</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">return [
|
|
// ...
|
|
'modules' => [
|
|
'user' => [
|
|
'logoutUrl' => 'https://auth.domain.com/?logout=1',
|
|
],
|
|
]
|
|
];</pre>
|
|
|
|
<p>
|
|
User can now log in through <abbr title="Single Sign On">SSO</abbr> using a button on humhub logging page. If you want to remove this intermediate login page, so user are automatically logged in through <abbr title="Single Sign On">SSO</abbr> when they first access Humhub, you can set up a redirection in the http server in front of the application :
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Example in apache</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">RewriteEngine On
|
|
RewriteCond %{QUERY_STRING} !nosso [NC]
|
|
RewriteRule "^/user/auth/login$" "/user/auth/external?authclient=lemonldapng" [L,R=301]</pre>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Example in nginx</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">if ($query_string !~ "nosso"){
|
|
rewrite ^/user/auth/login$ /user/auth/external?authclient=lemonldapng permanent;
|
|
}</pre>
|
|
|
|
<p>
|
|
If the authentication was successful but the user could not be registered in Humhub (which often happen if there is a conflict between source, username or email), Humhub will redirect to the login page to display the error, which trigger a redirection to the portal, ultimately triggering a loop error while registration error is not displayed.
|
|
</p>
|
|
|
|
<p>
|
|
To change this behavior and display the registration error, AuthController.onAuthSuccess method needs to be adapted so redirect to <abbr title="Single Sign On">SSO</abbr> will be bypassed when a registration error occured. This works for version 1.3.15 :
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Go to {humhub_home} folder</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> Execute</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">sed -i "s|return \$this->redirect(\['/user/auth/login'\]);|return \$this->redirect(['/user/auth/login','nosso'=>'showerror']);|" protected/humhub/modules/user/controllers/AuthController.php</pre>
|
|
|
|
</div>
|
|
<!-- EDIT4 SECTION "Configuring HumHub" [1451-4994] -->
|
|
<h3 class="sectionedit5" id="configuring_lemonldap">Configuring LemonLDAP</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
If not done yet, configure LemonLDAP::NG as an <a href="../openidconnectservice.html" class="wikilink1" title="documentation:2.0:openidconnectservice"> OpenID Connect service</a>.
|
|
</p>
|
|
|
|
<p>
|
|
Then, configure LemonLDAP::NG to recognize your HumHub instance as a valid <a href="../idpopenidconnect.html" class="wikilink1" title="documentation:2.0:idpopenidconnect"> new OpenID Connect Relying Party </a> using the following parameters:
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> <strong>Client ID</strong>: the same you set in HumHub configuration</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> <strong>Client Secret</strong>: the same you set in HumHub configuration</div>
|
|
</li>
|
|
<li class="level2"><div class="li"> Add the following <strong>exported attributes</strong></div>
|
|
<ul>
|
|
<li class="level4"><div class="li"> <strong>given_name</strong>: user's givenName attribute</div>
|
|
</li>
|
|
<li class="level4"><div class="li"> <strong>family_name</strong>: user's sn attribute</div>
|
|
</li>
|
|
<li class="level4"><div class="li"> <strong>email</strong>: user's mail attribute</div>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="level2"><div class="li"> <strong>Redirect URIs</strong> containing your Yii2 auth client ID.</div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Configuration sample using CLI:
|
|
</p>
|
|
<pre class="code"> $ /usr/libexec/lemonldap-ng/bin/lemonldap-ng-cli -yes 1 \
|
|
addKey \
|
|
oidcRPMetaDataExportedVars/humhub given_name givenName \
|
|
oidcRPMetaDataExportedVars/humhub family_name sn \
|
|
oidcRPMetaDataExportedVars/humhub email mail \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsClientID myClientId \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsClientSecret myClientSecret \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsRedirectUris 'https://humhub.example.com/user/auth/external?authclient=lemonldapng' \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsPostLogoutRedirectUris 'https://humhub.example.com' \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsIDTokenSignAlg RS512 \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsIDTokenExpiration 3600 \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsAccessTokenExpiration 3600 \
|
|
oidcRPMetaDataOptions/humhub oidcRPMetaDataOptionsBypassConsent 1 && \</pre>
|
|
|
|
</div>
|
|
<!-- EDIT5 SECTION "Configuring LemonLDAP" [4995-6736] -->
|
|
<h3 class="sectionedit6" id="migrate_former_local_or_ldap_humhub_account_to_connect_through_sso">Migrate former local or ldap Humhub account to connect through SSO</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
You need to manually update Humhub database to swith authentication mode to LemonLDAP::NG.
|
|
</p>
|
|
|
|
<p>
|
|
Table "user":
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Columns "username" and "email" should match exactly OIDC sub and email attributes ;</div>
|
|
</li>
|
|
<li class="level1"><div class="li"> If former ldap user, change column "auth_mode" to "local".</div>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Table "user_auth":
|
|
</p>
|
|
<ul>
|
|
<li class="level1"><div class="li"> Add an entry with user_id, username and "lemonldapng" as source (or the name you chose in your connector configuration) :</div>
|
|
</li>
|
|
</ul>
|
|
<pre class="code">+---------+-------------+-------------+
|
|
| user_id | source | source_id |
|
|
+---------+-------------+-------------+
|
|
| 4 | lemonldapng | jdoe |</pre>
|
|
|
|
</div>
|
|
<!-- EDIT6 SECTION "Migrate former local or ldap Humhub account to connect through SSO" [6737-7396] -->
|
|
<h3 class="sectionedit7" id="troubleshooting">Troubleshooting</h3>
|
|
<div class="level3">
|
|
|
|
<p>
|
|
If LemonLDAP login page freezes because of a browser security blockage, adapt security's CSP Form Action to allow HumHub host :
|
|
</p>
|
|
<pre class="code"> $ /usr/libexec/lemonldap-ng/bin/lemonldap-ng-cli -yes 1 \
|
|
set \
|
|
cspFormAction "'self' https://*.example.com"</pre>
|
|
|
|
</div>
|
|
<!-- EDIT7 SECTION "Troubleshooting" [7397-] --></div>
|
|
</body>
|
|
</html>
|