This document explains how to implement Monosign with mailcow: dockerized, the open-source mail server suite with a web interface and SOGo webmail. It covers Single Sign-On with OpenID Connect (OIDC), which is built into mailcow as the Generic-OIDC identity provider. Mailcow uses the Authorization Code flow, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the mailcow documentation (opens in a new tab) about the identity provider.
This configuration was tested with mailcow 2026-10. If your version is different, please check the mailcow documentation.
Mailcow supports OpenID Connect (Generic-OIDC and Keycloak) and LDAP as external identity providers. SAML is not available. The provider is configured in the mailcow admin interface (System → Configuration → Access → Identity Provider).
Monofor has no responsibility to do mailcow configurations. If you need support please contact the mailcow community or your mailcow support provider.
Mailcow is free and open source (GPLv3). Single sign-on with OpenID Connect 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 mailcow application
Configuration Single Sign-On for mailcow
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.
Mailcow 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 |
| Mailcow is accessed through a web browser. Options: Web, Mobile, Desktop, API. |
Url | Optional | Leave empty or enter the address of mailcow (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). Mailcow needs the e-mail address and the name of the user. |
With Auto-create users on login enabled (step 4), mailcow creates a mailbox for every Monosign user who signs in for the first time. 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 Mailcow application are provided as follows:
Monosign value | Example | Used in mailcow as |
|---|---|---|
Client Id |
| Client ID |
Client Secret |
| Client Secret |
Auth Url |
| Authorization endpoint |
Access Token Url |
| Token endpoint |
User Info Url |
| User info endpoint |
Mailcow does not read the OIDC discovery document, so the three addresses are entered one by one. Copy them from the Monosign Access Key Details.
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 redirect address of mailcow 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. Mailcow uses its main address without a path and without a slash at the end. It must be exactly the Redirect Url that is entered in the mailcow identity provider settings (step 4). Use the public (HTTPS) address of mailcow. |
Scope |
| Enter the three scopes one by one. They must be the same as the Client Scopes of mailcow (step 4). |
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 redirect address in the Resource field. |
Mailcow identifies the user by the email claim of the user information and uses the name of the user for the mailbox. Monosign returns them by default, so a claim mapping is not required.
3- Assign a User to the Mailcow 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 mailcow, 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 mailcow with Monosign. |
Expiration Date | Default one year | The assignment expires on this date. |
4- Configuration Single Sign-On for Mailcow
As we mentioned at the start, please check out the mailcow documentation first. Before the first sign-in add the e-mail domain of your users in mailcow under E-Mail → Configuration → Domains (for example the part after the @ of the e-mail address in Monosign). Then log in to the mailcow admin interface, open System → Configuration → Access → Identity Provider, select Generic-OIDC, fill in the fields below and click Save changes.
Field | Value | Description |
|---|---|---|
Identity Provider |
| Options: Keycloak, Generic-OIDC, LDAP. |
Authorization endpoint |
| Auth Url of the Monosign access key (step 1). |
Token endpoint |
| Access Token Url of the Monosign access key. |
User info endpoint |
| User Info Url of the Monosign access key. Mailcow reads the e-mail address and the name from it. |
Client ID / Client Secret | Client Id / Client Secret | Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. |
Redirect Url |
| Public HTTPS address of mailcow, without a path. It must match the Allowed Redirect URI of step 2. |
Client Scopes |
| The default of mailcow is |
Attribute Mapping → Default Template |
| Mailbox template that is used for new mailboxes (quota, permissions). No attribute mapping row is needed. |
Ignore SSL Errors | Disabled | Keep it off; mailcow must be able to verify the certificate of Monosign. |
Auto-create users on login | Enabled | Creates the mailbox at the first sign-in. The domain of the e-mail address of the user must exist in mailcow and be active. |
The Test Connection button of mailcow reports an error with Monosign. For Generic-OIDC it sends an OPTIONS request to the token endpoint and expects the answer 200, which Monosign does not give. This does not affect the sign-in; ignore it and test the sign-in itself (step 5).
The Disable mailcow Login and show only Single Sign-On option of the same page hides the user name and password form on the login page. Use it only after the single sign-on works, otherwise you can lock yourself out of the admin interface. A mailbox that is created by the single sign-on has no mailcow password; the user signs in only with Monosign.
5- Sign In Test
Now try to log in to mailcow using Monosign SSO. Open a new browser window (or a private window) and type the address of mailcow. The login page shows the Single Sign-On button below or login with.
Click the Single Sign-On 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 mailcow. At the first sign-in mailcow creates the mailbox of the user (the e-mail address and the name come from Monosign) and opens the webmail (SOGo) of the new mailbox.
Troubleshooting
Symptom | Cause | Solution |
|---|---|---|
The Single Sign-On button is not shown | The identity provider is not saved, or one of the required fields (endpoints, Client ID, Client Secret, Redirect Url) is empty. | Fill in all fields (step 4) and click Save changes. |
Monosign shows a redirect URI error | The Redirect Url of mailcow does not exactly match the Allowed Redirect URIs of Monosign (for example a slash or a path at the end), or it was entered in another field such as Resource. | Use the same address, without a path, in both places (steps 2 and 4). |
Monosign shows an invalid scope error | The default scope | Set Client Scopes to |
Mailcow shows only login failed after returning from Monosign | The e-mail domain of the user is not a mailcow domain or is inactive, so the mailbox cannot be created. Mailcow does not show the reason. | Add the domain of the e-mail address in E-Mail → Configuration → Domains and try again (step 4). |
Mailcow refuses the sign-in for another reason | Auto-create users on login is off and the mailbox does not exist, a mailbox with the same address exists but was not created by the single sign-on, or the user information has no | Enable the option, set |
The Test Connection button shows an error | Mailcow tests the token endpoint with an | Ignore the test; it does not affect the sign-in. |
A user cannot sign in | The user is not assigned to the application. | Assign the user in step 3. |
After completing the configuration on mailcow 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.