Notifo OIDC Integration

This document explains how to implement Monosign with Notifo, the open-source, self-hosted multi-channel notification platform (web push, e-mail, SMS, mobile push and more). It covers Single Sign-On with OpenID Connect (OIDC), which is built into Notifo. Notifo 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 Notifo configuration documentation (opens in a new tab).

This configuration is done with the Notifo 1.x Docker image (squidex/notifo:1) running on Docker with PostgreSQL. Notifo also supports MongoDB, MySQL and SQL Server. If your Notifo version or deployment type is different, please check the Notifo documentation.

Notifo supports OpenID Connect through one generic OIDC provider and the ready-made Google and GitHub logins. SAML is not available. There is no single sign-on screen in the Notifo interface; the provider is configured with environment variables (or in appsettings.json).

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

Notifo is free and open source (MIT). Single sign-on is not limited by a license, so it works in the self-hosted version without a 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 Notifo application
Configuration Single Sign-On for Notifo
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.

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

Notifo creates an account for every Monosign user who signs in for the first time, after the user accepts the terms of service and the privacy policy. 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	`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 Notifo application are provided as follows:

Monosign value	Example	Used in Notifo as
Client Id	`<client-id>`	`IDENTITY__OIDCCLIENT`
Client Secret	`<client-secret>`	`IDENTITY__OIDCSECRET`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`IDENTITY__OIDCAUTHORITY`. Notifo needs the address without the `.well-known/openid-configuration` part, for example `https://<monosign-host>/`. It reads the discovery document below this address.

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings. Enter the scopes that Notifo requests and add the callback address of Notifo to Allowed Redirect URIs, then press Update.

Property	Value	Description
Scope	`openid` `profile` `email`	The scopes that Notifo sends in the authorization request. Notifo adds `openid` and `profile` by itself and `email` comes from the option `IDENTITY__OIDCSCOPES` (default). Add each scope separated by space.
Allowed Redirect URIs	`https://<notifo-address>/signin-oidc`	The address where Monosign sends the user back after sign-in. The path `/signin-oidc` is the default callback path of the ASP.NET Core OpenID Connect handler that Notifo uses. Use the public (HTTPS) address of Notifo; it must be the same as `URLS__BASEURL` of step 4.
Signing Key / Key Id / Password, Issuer, Audience, Resource	Empty	Optional custom JWT settings. They are not needed. Do not enter the callback address in the Resource field.
Token lifetimes, CORS	Empty	Default values are used.

Notifo needs the email claim of the user; without it the sign-in is refused. Monosign returns the claim email by default, so a claim mapping is not required.

3- Assign a User to the Notifo Application

Open the Notifo application in Monosign, click the Assignments tab and click Assign a User.

Search and select the users who can sign in to Notifo, 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 Notifo with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for Notifo

As we mentioned at the start, please check out the Notifo documentation first. Notifo is configured with environment variables. In the Docker Compose deployment add the following variables to the environment of the Notifo container and replace the placeholder values.

URLS__BASEURL=https://<notifo-host-name>
IDENTITY__OIDCNAME=Monosign
IDENTITY__OIDCAUTHORITY=https://<monosign-host>/
IDENTITY__OIDCCLIENT=<client-id>
IDENTITY__OIDCSECRET=<client-secret>
IDENTITY__OIDCRESPONSETYPE=code
IDENTITY__GITHUBCLIENT=
IDENTITY__GITHUBSECRET=
IDENTITY__GOOGLECLIENT=
IDENTITY__GOOGLESECRET=

Variable	Value	Description
URLS__BASEURL	`https://<notifo-host-name>`	Exact public HTTPS address of Notifo. The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2.
IDENTITY__OIDCNAME	`Monosign`	Text on the sign-in button. Default: OIDC.
IDENTITY__OIDCAUTHORITY	`https://<monosign-host>/`	Issuer of Monosign. Notifo reads `.well-known/openid-configuration` below this address and checks the issuer of the tokens, so keep the slash at the end. Required.
IDENTITY__OIDCCLIENT / IDENTITY__OIDCSECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. The provider is enabled only when the authority and the client id are set.
IDENTITY__OIDCRESPONSETYPE	`code`	The default of Notifo is `id_token` (implicit flow). Set `code` to use the Authorization Code flow with the client secret.
IDENTITY__OIDCSCOPES	`email` (default)	Optional. Additional scopes. Notifo always requests `openid` and `profile`.
IDENTITY__OIDCGETCLAIMSFROMUSERINFOENDPOINT	`false` (default)	Optional. Set `true` if the claims are not in the ID token.
IDENTITY__ALLOWPASSWORDAUTH	`true` (default)	Optional. The local e-mail and password login stays available next to Monosign. Set it to `false` only after the single sign-on works, otherwise you can lock yourself out.
IDENTITY__GITHUB* / IDENTITY__GOOGLE*	Empty	The defaults belong to notifo.io and do not work for your domain. Leave them empty to hide the GitHub and Google buttons.

The first user of a new Notifo installation becomes the host administrator. A new installation redirects to /account/setup, where the first administrator is created with an e-mail address and a password. Create this local administrator account before turning on the single sign-on, so that the first Monosign user does not become the administrator by accident.

The environment contains the client secret and the secrets of the application. Store it in a file with restricted permissions (for example chmod 600) and do not store it in a shared repository. Before you go live also replace the web push keys (WEBPUSH__VAPIDPUBLICKEY, WEBPUSH__VAPIDPRIVATEKEY) as described in the Notifo documentation.

For reference, the Docker Compose file below shows the layout of the installation (Notifo with PostgreSQL). It will be replaced by the file that was tested for this document.

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./pgdata:/var/lib/postgresql/data
  notifo:
    image: squidex/notifo:1
    restart: unless-stopped
    ports:
      - "6277:80"
    env_file: .env
    environment:
      - STORAGE__TYPE=Sql
      - STORAGE__SQL__PROVIDER=Postgres
      - STORAGE__SQL__CONNECTIONSTRING=Server=db;Port=5432;Database=notifo;Username=notifo;Password=${POSTGRES_PASSWORD}
      - MESSAGING__TYPE=Sql
    depends_on:
      - db

When Notifo is behind a reverse proxy, the proxy must send the header X-Forwarded-Proto: https and forward the host name of URLS__BASEURL. After changing the environment, recreate the container so that the new variables are loaded:

docker compose up -d --force-recreate notifo

5- Sign In Test

Now try to log in to Notifo using Monosign SSO.

Open a new browser window (or a private window) and type the Notifo address. The login page of Notifo shows the e-mail and password form and, next to it, the Monosign button.
Click the 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 Notifo (/signin-oidc). At the first sign-in Notifo asks you to accept the terms of service and the privacy policy, creates the account with the e-mail address from Monosign and opens the Notifo dashboard.

Troubleshooting

Symptom	Cause	Solution
The Monosign button is not shown	`IDENTITY__OIDCAUTHORITY` or `IDENTITY__OIDCCLIENT` is not set, so the provider is disabled, or the container was not recreated after the change.	Set both variables (step 4) and run `docker compose up -d --force-recreate notifo`.
Monosign shows a redirect URI error	The redirect address that Notifo sends does not exactly match the Allowed Redirect URIs, for example because `URLS__BASEURL` is wrong, the proxy does not send `X-Forwarded-Proto: https` so the address starts with `http://`, or the address was entered in another field such as Resource.	Add `https://<notifo-address>/signin-oidc` to Allowed Redirect URIs in Monosign (step 2), set `URLS__BASEURL` to the same public HTTPS address and make the proxy send the header.
An error page appears after returning from Monosign	The Client Id or Client Secret is wrong, the issuer does not match (the slash at the end is missing), or the container cannot reach Monosign.	Copy the values again from the Monosign access key (step 1), use the issuer with the slash at the end and read the Notifo container log. Check the DNS and firewall rules of the Notifo host.
The login page shows an error that the e-mail address is private	The ID token has no `email` claim.	Set `Profile Access Type` to All (step 1) and keep the scope `email`; set `IDENTITY__OIDCGETCLAIMSFROMUSERINFOENDPOINT=true` if the claim is only in the user information.
The sign-in is refused because the e-mail address is already used	A local Notifo account with the same e-mail address and a login exists.	Sign in with the local account, or use a user with a new e-mail address.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
SAML sign-in is required	Notifo supports OpenID Connect only, not SAML.	Use the OIDC integration in this document.

After completing the configuration on Notifo 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 Notifo address may cause errors.