Mail-Archiver OIDC Integration

This document explains how to implement Monosign with Mail-Archiver, the open-source application that archives e-mails from IMAP, POP3 and other mail accounts. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Mail-Archiver. Mail-Archiver discovers the Monosign addresses from the OIDC discovery document, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to start with the Mail-Archiver OIDC guide.

This configuration is done with Mail-Archiver 2609.1 running on Docker Compose (images s1t5/mailarchiver:2609.1 and postgres:17-alpine). If your Mail-Archiver version or deployment type is different, please check the Mail-Archiver documentation.

Mail-Archiver supports OpenID Connect only. SAML is not available in Mail-Archiver. The settings section of the application is named OAuth, but the sign-in is an OpenID Connect authorization code flow with PKCE.

Monofor has no responsibility to do Mail-Archiver configurations. If you need support please contact the Mail-Archiver community or your Mail-Archiver 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 Mail Archiver application
Configuration Single Sign-On for Mail-Archiver
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.

Applications page in Monosign (1: Applications menu, 2: Add New)

Mail-Archiver is not in the application catalog, so click Create from scratch.

Creating a new application from scratch (1: Create from scratch)

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

New Application - Application tab (1: Name, 2: Next)

Property	Value	Description
Name	`Mail Archiver`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Mail-Archiver is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Mail-Archiver address.
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	`Enabled`	Displays the application on the user portal.

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

New Application - Access tab (1: Profile Access Type, 2: Create Application)

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	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All). Mail-Archiver 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.

Keys tab of the Mail Archiver application (1: Keys, 2: Add New Access Key)

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

Creating the OIDC/OpenID Access Key (1: Type OIDC/OpenID, 2: Create)

Property	Value	Options
Type	`OIDC/OpenID`	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`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

Configuration details for the Mail Archiver application are provided as follows:

Monosign value	Example	Used in Mail-Archiver as
Client Id	`<client-id>`	`OAuth__ClientId`
Client Secret	`<client-secret>`	`OAuth__ClientSecret`
Issuer (Configuration Url without the `.well-known/openid-configuration` part)	`https://<monosign-host>/`	`OAuth__Authority`. Mail-Archiver adds `.well-known/openid-configuration` itself and reads the Auth, Token, UserInfo and JWKS addresses from it.

2- Configuring the OIDC/OpenID Settings on Monosign

Open the key with the Configure button, go to OIDC/OpenID Settings and add the callback address of Mail-Archiver to Allowed Redirect URIs.

Property	Value	Description
Allowed Redirect URIs	`https://<mail-archiver-address>/oidc-signin-completed`	The address where Monosign sends the user back after sign-in. The path `/oidc-signin-completed` is fixed by Mail-Archiver. Use the public (HTTPS) address of Mail-Archiver; the host name must be the same as the one users type in the browser.
Signing Key / Key Id / Password, Issuer, Audience, Scope, Resource	Empty	Optional custom JWT settings. They are not needed. Mail-Archiver sends the scope itself (`openid profile email`).
Token lifetimes, CORS	Empty	Default values are used.

Mail-Archiver reads the user information from the Monosign UserInfo endpoint: sub, the name (name, or preferred_username, or given_name) and email. Monosign returns these claims by default, so a claim mapping is not required. The e-mail address is required.

To let the user return to the Mail-Archiver sign-in page after signing out, add the address of the page to the Allowed Redirect Urls for Logout. Open the application with Edit.

On the Login tab enter the address and click Save.

Login tab of the application (1: Login tab, 2: Allowed Redirect Urls for Logout, 3: Save)

Property	Value	Description
Allowed Redirect Urls for Logout	`https://<mail-archiver-address>/Auth/Login`	When the user signs out, Mail-Archiver asks Monosign to end the session and to send the browser back to its sign-in page. Monosign accepts only the addresses that are listed here.
Login Url, Login Callback Url	Empty	Not used. The sign-in is started from the Mail-Archiver sign-in page.

3- Assign a User to the Mail Archiver Application

Please follow the below instructions on how to assign a user to the Mail Archiver application. Open the application, click the Assignments tab and click Assign a User.

Assignments tab of the Mail Archiver application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to Mail-Archiver, check the Expiration Date and save. You can select more than one user.

Assign a User dialog (1: select the users, set the Expiration Date)

Property	Value	Description
User(s)	Selected users	Users who can sign in to Mail-Archiver with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Mail-Archiver

As we mentioned at the start, please check out the Mail-Archiver documentation first. Mail-Archiver is configured with environment variables (or the OAuth section of appsettings.json); there is no single sign-on screen in the Mail-Archiver interface. In the Docker Compose deployment add the following variables to the environment of the mailarchive-app service and replace the placeholder values.

Bash

OAuth__Enabled=true
OAuth__Authority=https://<monosign-host>/
OAuth__ClientId=<client-id>
OAuth__ClientSecret=<client-secret>
OAuth__DisplayName=Monosign
OAuth__ClientScopes__0=openid
OAuth__ClientScopes__1=profile
OAuth__ClientScopes__2=email
OAuth__DisablePasswordLogin=false
OAuth__AutoRedirect=false
OAuth__AutoApproveUsers=false
OAuth__AdminEmails__0=<administrator-e-mail-address>
AllowedHosts=<mail-archiver-host-name>

Variable	Value	Description
OAuth__Enabled	`true`	Enables the OpenID Connect login.
OAuth__Authority	`https://<monosign-host>/`	Issuer address of Monosign. Mail-Archiver compares the issuer of the ID token with this value, so it must be exactly the `issuer` of the discovery document, including the trailing slash.
OAuth__ClientId / OAuth__ClientSecret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
OAuth__DisplayName	`Monosign`	Text of the button on the sign-in page (“Login with Monosign”).
OAuth__ClientScopes__0…2	`openid`, `profile`, `email`	Scopes that Mail-Archiver requests.
OAuth__DisablePasswordLogin	`false`	Keeps the local user name and password login next to the Monosign button. Set to `true` to allow only the single sign-on.
OAuth__AutoRedirect	`false`	Sends the user directly to Monosign without showing the sign-in page. It works only when `OAuth__DisablePasswordLogin` is `true`.
OAuth__AutoApproveUsers	`false`	When `false`, a new Monosign user is created inactive and an administrator has to activate the account (see the note below).
OAuth__AdminEmails__0	E-mail address of the administrator	A user who signs in with this e-mail address is created as an active administrator. Add one entry for each administrator (`OAuth__AdminEmails__1`, …).
AllowedHosts	Host name of Mail-Archiver	Mail-Archiver answers only the host names in this list (separated by `;`). Add the host name that users type in the browser.

A successful sign-in at Monosign is not the end of the story. After Monosign accepts the user, Mail-Archiver decides locally: if the e-mail address is in OAuth__AdminEmails, the user is created as an active administrator; an existing active user signs in; a new user is active only when OAuth__AutoApproveUsers is true, otherwise the account is created inactive and the user sees “Account pending approval” until an administrator activates it on the Users page.

The environment file contains the client secret and the password of the local administrator. Restrict its permissions (for example chmod 600) and do not store it in a shared repository.

Recreate the Mail-Archiver container so that the new variables are loaded:

Bash

cd /opt/mail-archiver
docker compose up -d --force-recreate mailarchive-app

The sign-in page must now show the user name and password form and the “Login with Monosign” button.

Now try to log in to Mail-Archiver using Monosign SSO.

Open a new browser window (or a private window) and type the Mail-Archiver address. The sign-in page shows the local form and the Login with Monosign button.

Mail-Archiver sign-in page with the “Login with Monosign” button

Click Login with Monosign. Mail-Archiver redirects the browser to the Monosign sign-in page of the Mail Archiver application. You can 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 Mail-Archiver (/oidc-signin-completed). Mail-Archiver creates the account on the first sign-in and opens the dashboard. The signed-in user is shown at the top right.

User logged in to Mail-Archiver through Monosign SSO (Dashboard and the user menu)

When you open Mail-Archiver from the Monosign portal, the sign-in page of Mail-Archiver opens and you click Login with Monosign once. The sign-in of Mail-Archiver is started by a form on its own page, so Monosign cannot start it with a link.

Troubleshooting

Symptom	Cause	Solution
“Account pending approval” after the sign-in at Monosign succeeded	The user is new and `OAuth__AutoApproveUsers` is `false`.	Activate the user on the Users page with an administrator account, add the e-mail address to `OAuth__AdminEmails`, or set `OAuth__AutoApproveUsers=true`.
The “Login with Monosign” button is not shown	`OAuth__Enabled` is not `true`, or the container was not recreated.	Set the variables and run `docker compose up -d --force-recreate mailarchive-app`.
Monosign shows a redirect URI error	The redirect URI that Mail-Archiver sends does not exactly match the Allowed Redirect URIs.	Add `https://<mail-archiver-address>/oidc-signin-completed` in Monosign (step 2).
Mail-Archiver reports an authentication error after returning from Monosign	`OAuth__Authority` is not exactly the issuer of the discovery document (for example the trailing slash is missing).	Use the `issuer` value of `https://<monosign-host>/.well-known/openid-configuration` exactly as it is.
Mail-Archiver answers 400 Bad Request for the address	The host name is not in `AllowedHosts`.	Add the host name that is used in the browser to `AllowedHosts` and recreate the container.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
After Sign Out the browser does not return to the Mail-Archiver sign-in page	The sign-in page address is not listed in Allowed Redirect Urls for Logout.	Add `https://<mail-archiver-address>/Auth/Login` on the Login tab of the application (step 2).
The local user name and password form is not shown	`OAuth__DisablePasswordLogin` is `true`.	Set it to `false` and recreate the container.
SAML sign-in is required	Mail-Archiver supports OpenID Connect only.	Use the OIDC integration in this document.

After completing the configuration on Mail-Archiver and Monosign, it is better to test in a new private browser window if the OIDC SSO doesn’t work, because old session cookies of the Mail-Archiver address may cause errors.