This document explains how to implement Monosign with HumHub, the open source social network kit for organizations. It covers Single Sign-On with OpenID Connect (OIDC). HumHub does not have an OIDC administration screen in the core, so the community module OIDC Login is used; it uses the Authorization Code flow and the OIDC/OpenID access key of Monosign. Before you continue, it is better to read the HumHub documentation (opens in a new tab) and the README of the module (opens in a new tab).
This configuration was tested with HumHub 1.19 (official humhub/humhub:stable Docker image) and OIDC Login 1.0.0 (requires HumHub 1.18 or newer, AGPL-3.0). If your versions are different, please check the HumHub documentation.
The module is configured in the HumHub administration interface under Administration → OIDC Login. SAML is not covered in this document.
Monofor has no responsibility to do HumHub configurations. If you need support please contact the HumHub community or your HumHub support provider. OIDC Login is a community module and is not maintained by HumHub GmbH.
Instructions
This documentation contains 5 main steps for integration.
Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the HumHub application
Configuration Single Sign-On for HumHub
Sign In Test
1- Creating an Application on Monosign
Create your application on Monosign first. Open the Applications page from the left menu and click Add New.
HumHub is not in the application catalog, so click Create from scratch.
Fill in the application details on the Application tab and click Next.
Property | Value | Description |
|---|---|---|
Name |
| Name of the application shown to users on the Monosign portal and on the Monosign sign-in page. |
Type |
| HumHub is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of HumHub (for example |
Logo | Optional | Browse and upload a logo (PNG or JPG, max 1 MB); it is also shown on the Monosign sign-in page. |
Users can see this application on their list |
| Displays the application on the user portal. |
On the Access tab define who can reach the application and click Create Application.
Property | Value | Description |
|---|---|---|
User Access Type |
| Defines which users can access this application. Options: Only Assigned Users, All Users, System Default. |
User Group Access Type |
| Defines the application’s user group access. |
Source Using Type |
| Defines which user sources the application can use. |
Profile Access Type |
| Defines which user profile attributes are available to the application (Options: Restricted, All). HumHub needs the e-mail address of the user. |
After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.
Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.
Configuration details for the HumHub application are provided as follows:
Monosign value | Example | Used in HumHub as |
|---|---|---|
Client Id |
| Client ID |
Client Secret |
| Client secret |
Issuer |
| Provider address. Enter the root address of Monosign without a path; HumHub finds the other addresses from the discovery document (the Configuration Url of the key). |
2- Configuring the OIDC/OpenID Settings on Monosign
Open the Keys tab of the application and click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings.
Add the callback address of HumHub to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.
Property | Value | Description |
|---|---|---|
Allowed Redirect URIs |
| The address where Monosign sends the user back after sign-in. HumHub shows the same value as Redirect URI on the OIDC Login page (step 4). The last part ( |
Scope |
| Enter the three scopes one by one. |
Other fields | Empty / default | The other fields (Issuer, Audience, Resource, token lifetimes, CORS) are not needed. |
3- Assign a User to the HumHub Application
Open the application in Monosign, click the Assignments tab and click Assign a User.
Search and select the users who can sign in to HumHub, check the Expiration Date and save. You can select more than one user. Every user needs an e-mail address in Monosign.
4- Configuration Single Sign-On for HumHub
As we mentioned at the start, please check out the HumHub documentation first. First install the module OIDC Login: copy the oidc-login folder of the module to the custom module folder of HumHub (with the official Docker image: /data/modules-custom/), then enable it in Administration → Modules (or with yii module/enable oidc-login). After that log in to HumHub with an administrator account, open Administration → OIDC Login, fill in the fields below and click Save.
Field | Value | Description |
|---|---|---|
Provider address |
| Root address of Monosign, no path. Discovery finds the endpoints. |
Client ID | Client Id | Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. |
Client secret | Client Secret | Copied from the same page. |
Provider name |
| Name of the provider shown on the sign-in button. OIDC Login 1.0.0 needs a small change for this; see the note about the button label below. |
Enabled | On | Adds the external provider button to the HumHub login page. |
Create an account for someone signing in for the first time | On (default) | A user who signs in through Monosign for the first time gets a HumHub account. Turn it off to allow only users whose account is already linked. |
Hide the local login form | Off | Optional. When it is on, the local password form is hidden and Monosign is the only way in. The way back in stays open at |
HumHub requires HTTPS for this module. The page shows the Redirect URI that has to be registered in Monosign (step 2). The Auth client ID is written into every linked account and cannot be changed after the first save; leave it empty to use oidc.
Existing accounts: if members already have HumHub accounts, link them to Monosign before the first sign-in; otherwise the first sign-in creates duplicate accounts. Run php protected/yii oidc-login-prelink (dry run) and then php protected/yii oidc-login-prelink --apply.
Behind a reverse proxy: if the Redirect URI on the OIDC Login page starts with http:// or contains :80, HumHub does not trust the proxy. Set the real address of HumHub in Administration → Settings and add the proxy addresses to the web configuration (protected/config/web.php, with the Docker image /data/config/web.php):
return [
'components' => [
'request' => [
'trustedHosts' => ['127.0.0.1', '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'],
'securePort' => 443,
],
],
];
The proxy must send X-Forwarded-Proto: https.
Button label: in OIDC Login 1.0.0 the sign-in button always shows the fixed text Aller à la connexion (French) and ignores the Provider name field, although the module already has a function that returns the provider name (Events::providerName()). To show the provider name on the button, change the function defaultTitle() in authclient/OidcAuth.php of the module:
protected function defaultTitle()
{
return \humhub\modules\oidcLogin\Events::providerName();
}
Restart HumHub (or clear the PHP opcache) after the change. This is a local change to a community module; check it again after a module update.
5- Sign In Test
Now try to log in to HumHub using Monosign SSO. Open a new browser window (or a private window) and type the address of HumHub. The login page shows the Monosign button under Or continue with.
Click the Monosign button once.
On the Monosign sign-in page log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.
After the sign-in Monosign redirects the browser back to HumHub (
/user/auth/external). At the first sign-in HumHub shows the Account registration page; enter a user name, the first name and the last name, then click Create account.
The user is signed in to HumHub. At the next sign-in the registration page is skipped.
HumHub creates the account of a new SSO user as a normal member. Administrator rights are not given by Monosign; an existing HumHub administrator has to give them in Administration → Users.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The provider button is not shown on the login page | The module is not enabled, Enabled is off, or a required field is empty. | Enable the module in Administration → Modules and check step 4. |
The button shows the French text Aller à la connexion instead of Monosign | OIDC Login 1.0.0 uses a fixed button text and ignores the Provider name. | Change |
Monosign shows a redirect URI error | The callback address does not exactly match the Allowed Redirect URIs, for example because it starts with | Use the Redirect URI shown on the OIDC Login page and fix the reverse proxy settings (see the note in step 4). |
An error appears after returning from Monosign | The Client Id or Client Secret is wrong, HumHub cannot reach Monosign, or the user has no e-mail address. | Copy the values again from the Monosign access key (step 1) and check that Monosign opens from the HumHub server. |
A second account is created for a member who already had an account | The existing accounts were not linked before the first sign-in. | Run |
You are not registered | Account creation on first sign-in is off and the user is not linked. | Turn on the account creation or link the user. |
Everyone is locked out of the local login | Hide the local login form is on. | Open |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
After completing the configuration on HumHub and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn’t work, because old session cookies may cause errors.














