This document explains how to implement Monosign with HyperKitty, the mailing list archive of GNU Mailman 3. HyperKitty and the list management interface Postorius run in the same Django web application (Mailman Web) and share one login page. It covers Single Sign-On with OpenID Connect (OIDC), which is provided by the django-allauth library as the OpenID Connect provider. Mailman Web 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 Mailman 3 documentation (opens in a new tab) and the django-allauth documentation (opens in a new tab) about the OpenID Connect provider.
This configuration was tested with HyperKitty 1.3.12, Postorius 1.3.13, django-mailman3 1.3.15 and django-allauth 65.20. If your versions are different, please check the Mailman 3 documentation.
The login page of Mailman Web supports social providers through django-allauth. The OpenID Connect provider is enabled in the Django settings file settings_local.py; the provider itself (Client Id, Client Secret and the address of Monosign) is then entered in the Django admin interface. SAML is not available.
Monofor has no responsibility to do Mailman configurations. If you need support please contact the Mailman community or your Mailman support provider.
Mailman 3, HyperKitty and Postorius are free and open source (GPLv3). Single sign-on is not limited by a license key.
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 HyperKitty application
Configuration Single Sign-On for HyperKitty
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.
HyperKitty 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 |
| HyperKitty is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of Mailman Web (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). Mailman Web needs the e-mail address and the name of the user. |
Mailman Web creates an account for every Monosign user who signs in for the first time (automatic sign-up). Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.
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.
Property | Value | Options |
|---|---|---|
Type |
| Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server |
Client Id / Client Secret | Generated automatically | Use the eye icon next to the secret to reveal it. Both values are required in step 4. |
Session |
| System Default, On-demand, Permanent |
State |
| Enabled, Disabled |
Never Expires |
| Turn off to define a specific expiration date for the key. |
Configuration details for the HyperKitty application are provided as follows:
Monosign value | Example | Used in Django admin as |
|---|---|---|
Client Id |
| Client id |
Client Secret |
| Secret key |
Configuration Url |
|
|
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 Mailman Web 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. The part |
Scope |
| Enter the three scopes one by one. django-allauth requests these scopes by default. |
Other fields | Empty / default | The other fields (Signing Key, Issuer, Audience, Resource, token lifetimes, CORS, Initiate Login URI) are not needed. Do not enter the callback address in the Resource field. |
django-allauth reads the e-mail address and the name of the user from the user information of Monosign. Monosign returns them by default, so a claim mapping is not required.
3- Assign a User to the HyperKitty 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 Mailman Web, check the Expiration Date and save. You can select more than one user.
Property | Value | Description |
|---|---|---|
User(s) | Selected users | Users who can sign in to Mailman Web with Monosign. |
Expiration Date | Default one year | The assignment expires on this date. |
4- Configuration Single Sign-On for HyperKitty
As we mentioned at the start, please check out the Mailman 3 documentation first. The configuration has two parts: enabling the provider in the Django settings and adding the provider in the Django admin interface.
4.1 Enable the OpenID Connect provider
Add the following lines to the file settings_local.py of Mailman Web and restart Mailman Web. With the Docker images of Mailman this file is web/settings_local.py in the folder that is mounted as /opt/mailman-web-data.
INSTALLED_APPS = list(INSTALLED_APPS) + [
'allauth.socialaccount.providers.openid_connect',
]
SOCIALACCOUNT_EMAIL_VERIFICATION = 'none'
SOCIALACCOUNT_AUTO_SIGNUP = True
Setting | Value | Description |
|---|---|---|
INSTALLED_APPS |
| Adds the generic OpenID Connect provider to the providers that are already enabled (GitHub, GitLab, Google). |
SOCIALACCOUNT_EMAIL_VERIFICATION |
| The default of Mailman Web is a mandatory e-mail confirmation. Monosign has already verified the user, so the confirmation e-mail is skipped for social sign-ins. |
SOCIALACCOUNT_AUTO_SIGNUP |
| Creates the account at the first sign-in without an extra sign-up form. |
In the Docker images of Mailman the list of apps is built from the lists DEFAULT_APPS and MAILMAN_WEB_SOCIAL_AUTH of the base settings, and INSTALLED_APPS is empty in settings_local.py. If the line above fails with the error name 'INSTALLED_APPS' is not defined, build the list from these two lists instead.
4.2 Add the provider in the Django admin interface
Log in to the Django admin interface of Mailman Web (https://<hyperkitty-address>/admin/) with a superuser account, open Social accounts → Social applications and click Add social application. Fill in the fields below and save.
Field | Value | Description |
|---|---|---|
Provider |
| The generic provider that was enabled in step 4.1. |
Provider ID |
| Identifier of the provider. It is part of the callback address (step 2). |
Name |
| Name on the sign-in button. |
Client id | Client Id | Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. |
Secret key | Client Secret | Copied from the same page. |
Key | Empty | Not used. |
Settings |
| Address of Monosign. django-allauth reads the endpoints from the discovery document below this address. |
Sites | The site of Mailman Web | Move the site of Mailman Web (the domain of the server) from Available sites to Chosen sites. Without it the button is not shown. |
The Django admin interface needs a superuser. In the Docker images the user is created with the variables MAILMAN_ADMIN_USER and MAILMAN_ADMIN_EMAIL at the first start and has no password; set one with python manage.py changepassword.
5- Sign In Test
Now try to log in to Mailman Web using Monosign SSO. Open a new browser window (or a private window) and type the address of Mailman Web, then click Sign In. The login page shows the Monosign button next to the other social providers.
Click the 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 Mailman Web (
/accounts/oidc/monosign/login/callback/). At the first sign-in the account is created with the name and the e-mail address from Monosign and the user is signed in to HyperKitty and Postorius.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The Monosign button is not shown | The provider is not in | Check step 4.1, restart Mailman Web and choose the site in step 4.2. |
Monosign shows a redirect URI error | The callback address does not exactly match the Allowed Redirect URIs, for example because the Provider ID is different, the slash at the end is missing, or the address starts with | Use |
An error page appears after returning from Monosign | The Client Id or Client Secret is wrong, | Copy the values again from the Monosign access key (step 1) and check that |
Mailman Web asks to confirm the e-mail address |
| Set it as in step 4.1 and restart Mailman Web. |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
After completing the configuration on Mailman Web 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.