Help

Integration

HumHub OIDC Integration

Updated 16 Nov 2026 8 min read

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.

  1. Creating an application on Monosign

  2. Configuring the OIDC/OpenID settings on Monosign

  3. Assign a user to the HumHub application

  4. Configuration Single Sign-On for HumHub

  5. 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.

image-20261030-191725.png

HumHub is not in the application catalog, so click Create from scratch.

image-20261030-191750.png

Fill in the application details on the Application tab and click Next.

humhub-01-application.jpg

Property

Value

Description

Name

HumHub

Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.

Type

Web

HumHub is accessed through a web browser. Options: Web, Mobile, Desktop, API.

Url

Optional

Leave empty or enter the address of HumHub (for example https://<humhub-address>).

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

Enabled

Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

image-20261030-192040.png

Property

Value

Description

User Access Type

System Default

Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.

User Group Access Type

System Default

Defines the application’s user group access.

Source Using Type

System Default

Defines which user sources the application can use.

Profile Access Type

System Default

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.

image-20261030-192203.png

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

humhub-02-key-type.jpg

Configuration details for the HumHub application are provided as follows:

humhub-04-key-details.jpg

Monosign value

Example

Used in HumHub as

Client Id

<client-id>

Client ID

Client Secret

<client-secret>

Client secret

Issuer

https://<monosign-host>

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.

image-20261031-211438.png

Add the callback address of HumHub to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.

humhub-03-oidc-settings.jpg

Property

Value

Description

Allowed Redirect URIs

https://<humhub-address>/user/auth/external?authclient=oidc

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 (oidc) is the Auth client ID of the module; do not change it after the first sign-in.

Scope

openid profile email

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.

image-20261030-193315.png

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.

image-20261030-193652.png

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.

humhub-05-module-settings.jpg

Field

Value

Description

Provider address

https://<monosign-host>

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

Monosign

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 /user/auth/login?showLoginForm=1.

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.

humhub-06b-login-page-monosign.jpg
  1. Click the Monosign button once.

  2. 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.

  3. 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.

humhub-07-registration.jpg
  1. The user is signed in to HumHub. At the next sign-in the registration page is skipped.

humhub-08-signed-in.jpg

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 defaultTitle() as described in the note about the button label (step 4).

Monosign shows a redirect URI error

The callback address does not exactly match the Allowed Redirect URIs, for example because it starts with http:// or contains :80.

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 oidc-login-prelink before the first sign-in (step 4); merge the duplicates manually afterwards.

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 /user/auth/login?showLoginForm=1.

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.

Permanent link