Postal OIDC Integration

This document explains how to implement Monosign with Postal, the open-source mail delivery platform for sending and receiving e-mail (SMTP and HTTP API) with a web interface. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Postal. Postal 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 Postal documentation (opens in a new tab).

This configuration was tested with Postal 3.3.7. If your version is different, please check the Postal documentation.

Postal supports OpenID Connect with one generic provider. SAML is not available. There is no single sign-on screen in the Postal web interface; OIDC is configured in the Postal configuration file postal.yml (or with environment variables).

Monofor has no responsibility to do Postal configurations. If you need support please contact the Postal community or your Postal support provider.

Postal is free and open source (MIT). Single sign-on with OpenID Connect is not limited by a license key.

Postal does not create users at the first single sign-on. The user must already exist in Postal (created by an administrator) with the same e-mail address as in Monosign. At the first sign-in Postal links the account to Monosign by the e-mail address; after that the account is matched by the Monosign user identifier.

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 Postal application
Configuration Single Sign-On for Postal
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.

Postal 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	`Postal`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Postal is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the address of Postal (for example `https://<postal-address>`). The sign-in is started from the Postal login page with the Login with Monosign button (see step 5).
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.

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). Postal 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.

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 Postal application are provided as follows:

Monosign value	Example	Used in Postal as
Client Id	`<client-id>`	`identifier`
Client Secret	`<client-secret>`	`secret`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`issuer`. Enter the address without the `.well-known/openid-configuration` part, for example `https://<monosign-host>/`. Postal reads the discovery document from this address.

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 Postal to Allowed Redirect URIs, enter the scopes in the Scope field, then press Update.

Property	Value	Description
Allowed Redirect URIs	`https://<postal-address>/auth/oidc/callback`	The address where Monosign sends the user back after sign-in. The path `/auth/oidc/callback` is fixed by Postal. Use the public (HTTPS) address of Postal, which is the `web_hostname` and `web_protocol` of its configuration.
Scope	`openid profile email`	Enter the three scopes one by one. They must be the same as the `scopes` of Postal (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 callback address in the Resource field.

Postal reads the user information of Monosign: sub (the user name in Monosign, which Postal stores as the identity of the user), email and the name of the user. The name needs a claim mapping in Postal, see name_field in step 4; no claim mapping is needed in Monosign.

3- Assign a User to the Postal 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 Postal, 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 Postal with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Postal

As we mentioned at the start, please check out the Postal documentation first. Add the oidc section to the configuration file postal.yml of Postal, replace the placeholder values and restart Postal (all components: web server, SMTP server and worker).

oidc:
  enabled: true
  local_authentication_enabled: true
  name: Monosign
  issuer: https://<monosign-host>/
  identifier: <client-id>
  secret: <client-secret>
  scopes:
    - openid
    - profile
    - email
  uid_field: sub
  email_address_field: email
  name_field: FormattedUserName
  discovery: true

Setting	Value	Description
enabled	`true`	Enables OpenID Connect. The same settings are available as environment variables (`OIDC_ENABLED`, `OIDC_ISSUER`, `OIDC_IDENTIFIER` and so on).
local_authentication_enabled	`true` (default)	Keeps the e-mail and password login next to Monosign. Set it to `false` only after the single sign-on works, otherwise you can lock yourself out.
name	`Monosign`	Name of the provider on the sign-in button (Login with Monosign).
issuer	`https://<monosign-host>/`	Issuer of Monosign. Postal reads `.well-known/openid-configuration` below this address. Keep the slash at the end, because the issuer of Monosign has it.
identifier / secret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
scopes	`openid`, `profile`, `email`	The default of Postal is only `openid` and `email`; add `profile` so that Postal receives the name of the user.
uid_field / email_address_field	`sub` / `email` (default)	Claims that identify the user and give the e-mail address. The defaults work with Monosign.
name_field	`FormattedUserName`	Required for Monosign. Postal splits the name into first and last name and needs both. The default claim `name` of Monosign is the user name without a space (for example `john.doe`), so the last name stays empty and the sign-in fails with a 422 error. `FormattedUserName` holds the display name with a space (for example John Doe).
discovery	`true` (default)	Postal finds the endpoints of Monosign from the discovery document. When set to `false`, the endpoints must be entered one by one.

The configuration file contains the client secret and the database passwords. Restrict its permissions (for example chmod 600) and do not store it in a shared repository.

Create the users in Postal before they sign in with Monosign (the administrator of Postal can do it in the web interface under Users, or on the server with postal make-user). The e-mail address of the Postal user must be the same as the e-mail address in Monosign. At the first sign-in Postal replaces the name of the user with the name from Monosign and removes the local password of the user, so the user signs in only with Monosign.

5- Sign In Test

Now try to log in to Postal using Monosign SSO. Open a new browser window (or a private window) and type the address of Postal. The login page shows the Login with Monosign button above the local login form.

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 Postal (/auth/oidc/callback). Postal finds the user by the e-mail address and opens the organizations page.

Troubleshooting

Symptom	Cause	Solution
The Login with Monosign button is not shown	`oidc.enabled` is not `true`, or Postal was not restarted after the change.	Set the section `oidc` (step 4) and restart all Postal components.
Monosign shows a redirect URI error	The callback address that Postal sends does not exactly match the Allowed Redirect URIs, for example because `web_hostname` or `web_protocol` is wrong, or the address was entered in another field such as Resource.	Add `https://<postal-address>/auth/oidc/callback` to Allowed Redirect URIs (step 2) and check `web_hostname` and `web_protocol`.
After returning from Monosign Postal shows The change you wanted was rejected (HTTP 422)	Postal could not save the user: the name from Monosign has no space, so the last name is empty. The default `name_field: name` is the user name of Monosign.	Set `name_field: FormattedUserName` (step 4) and restart the web server of Postal.
Postal shows An issue occurred while logging you in with OpenID	The Client Id or Client Secret is wrong, the issuer is wrong, or Postal cannot reach Monosign.	Copy the values again from the Monosign access key (step 1), use the issuer as in step 4 and read the log of the Postal web server.
Postal shows No user was found matching your identity	There is no Postal user with the e-mail address of the Monosign user, or the user is already linked to another identity.	Create the user in Postal with the same e-mail address (step 4).
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.

After completing the configuration on Postal 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.