This document explains how to implement Monosign with Listmonk, a self-hosted newsletter and mailing list manager. It covers Single Sign-On with OpenID Connect (OIDC). Listmonk reads the Monosign addresses from the OIDC discovery document and uses the Authorization Code flow, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Listmonk OIDC documentation (opens in a new tab).
This configuration was tested with Listmonk 6.2.0. If your version is different, please check the Listmonk documentation.
OIDC is configured in the Listmonk admin interface under Settings → Security → OIDC. SAML is not available.
Monofor has no responsibility to do Listmonk configurations. If you need support please contact the Listmonk community or your Listmonk support provider.
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 Listmonk application
Configuration Single Sign-On for Listmonk
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.
Listmonk 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 |
| Listmonk is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of the Listmonk admin page (for example |
Logo | Optional | Browse and upload a logo; 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). Listmonk needs the e-mail address and the name 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 Listmonk application are provided as follows:
Monosign value | Example | Used in Listmonk as |
|---|---|---|
Client Id |
| Client ID |
Client Secret |
| Client secret |
Configuration Url |
| Provider URL. Enter the address without the |
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 Listmonk 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. Listmonk shows this value as Redirect URL for oAuth provider on the OIDC settings page (step 4). It is built from the Root URL in Settings → General, so set the Root URL first. |
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 Listmonk 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 Listmonk, check the Expiration Date and save. You can select more than one user.
4- Configuration Single Sign-On for Listmonk
As we mentioned at the start, please check out the Listmonk documentation first. Log in to the Listmonk admin interface with a Super Admin user and set the Root URL to the public address of Listmonk in Settings → General (for example https://<listmonk-address>). Then open Settings → Security → OIDC, fill in the fields below and click Save.
Field | Value | Description |
|---|---|---|
Enable OIDC SSO |
| Shows the SSO button on the Listmonk login page. |
Provider URL |
| Address of Monosign. Listmonk reads the endpoints from the discovery document below this address. |
Provider name |
| Name on the SSO button of the login page (Login with Monosign). |
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. |
Auto-create users |
| If it is on, an account is created at the first sign-in. If it is off, a Listmonk user with the same e-mail address as the Monosign user must exist already. |
Default user role | A Listmonk user role | Role given to the users that are created automatically. |
Default list role | None or a list role | List role given to the users that are created automatically. |
Redirect URL for oAuth provider |
| Read-only. Add this address to the Allowed Redirect URIs in Monosign (step 2). |
Every user that is created automatically gets the Default user role. Do not choose a role with administrator permissions unless every user assigned to the application should be an administrator.
Listmonk matches the user by the e-mail address that Monosign returns. If the sign-in is refused, check that the e-mail address of the Listmonk user and of the Monosign user is the same.
5- Sign In Test
Now try to log in to Listmonk using Monosign SSO. Open a new browser window (or a private window) and type the address of the Listmonk admin page. The login page shows the Login with Monosign button (the name comes from the Provider name field).
Click the Login with Monosign button.
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 Listmonk (
/auth/oidc) and the user is signed in to the Listmonk admin interface.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The SSO button is not shown | OIDC SSO is not enabled or the settings were not saved. | Check step 4 and save the settings again. |
Monosign shows a redirect URI error | The callback address does not exactly match the Allowed Redirect URIs, for example because the Root URL of Listmonk is different or starts with | Set the Root URL in Settings → General and use the Redirect URL for oAuth provider value shown by Listmonk (step 2). |
An error appears after returning from Monosign | The Client Id or Client Secret is wrong, the Provider URL is wrong, or Listmonk cannot reach Monosign. | Copy the values again from the Monosign access key (step 1) and check that the Provider URL followed by |
The sign-in is refused after Monosign | No Listmonk user has the e-mail address of the Monosign user and Auto-create users is off. | Create the user in Listmonk with the same e-mail address, or turn on Auto-create users. |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
After completing the configuration on Listmonk 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.