Postiz OAuth2 Integration

This document explains how to implement Monosign with Postiz, the open-source social media scheduling tool. It covers Single Sign-On. Postiz supports single sign-on through its Generic OAuth provider, which works with any OpenID Connect (OIDC) compatible identity provider. Before you continue, it is better to start with the Postiz documentation.

This configuration is done with the self-hosted Postiz container image (ghcr.io/gitroomhq/postiz-app:latest) running with the official Docker Compose file of Postiz. If your Postiz version or deployment type is different, please check the Postiz documentation.

Postiz supports OAuth 2.0 / OpenID Connect only. SAML is not available in Postiz.

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

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Configuration Single Sign-On for Postiz
Assign a user to the Postiz application
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)

Postiz 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: Logo, 3: Next)

Property	Value	Description
Name	`Postiz`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	Postiz is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the Postiz address (for example `https://postiz.example.com`).
Logo	`postiz.png`	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. Postiz reads the `email` attribute of the user.

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

Keys tab of the Postiz 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. The secret is required in step 3.
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 Postiz application are provided as follows:

OIDC/OpenID Access Key Details (1: Configure)

Property	Value	Used in Postiz as
Client Id	`<client-id>`	`POSTIZ_OAUTH_CLIENT_ID`
Client Secret	`<client-secret>`	`POSTIZ_OAUTH_CLIENT_SECRET`
Grant Type	`Authorization Code`	The flow used by Postiz.
Auth Url	`https://<monosign-host>/openid/authorize`	`POSTIZ_OAUTH_AUTH_URL`
Access Token Url	`https://<monosign-host>/openid/token`	`POSTIZ_OAUTH_TOKEN_URL`
User Info Url	`https://<monosign-host>/openid/userinfo`	`POSTIZ_OAUTH_USERINFO_URL`
Configuration Url / JSON Web Key Set	`https://<monosign-host>/.well-known/…`	Not used. Postiz does not read the discovery document or validate the token itself.

The third step uses the Client Id, Client Secret, Auth Url, Access Token Url and User Info Url from the “OIDC/OpenID Access Key Details“ section above to configure Postiz.

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button on the OpenID Connect (OIDC) key and open the OIDC/OpenID Settings → Configuration tab. The default values are used for the Postiz integration.

Property	Value	Description
UserName Format	`Monosign UserName`	Defines the UserName format such as `Monosign UserName, sAMAccountName, UserPrincipalName, Email etc.`
Subject (sub) Format	`Default (user name based)`	How the `sub` claim is built. Postiz stores the `sub` value as the id of the user, so do not change it after users have signed in.
Signature Algorithm	Not selected	Postiz does not validate the token signature; it reads the user from the UserInfo endpoint, so no change is required.
Signing Key / Key Id / Password, Issuer, Audience, Scope, Resource	Empty	Optional custom JWT settings. They are not needed for Postiz.

Scroll down to Allowed Redirect URIs and add the callback address of Postiz.

Adding the Postiz redirect URI (Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://postiz.example.com/settings`	The address where Monosign sends the user back after sign-in. Postiz always uses `<FRONTEND_URL>/settings` as the redirect URI, so the host name must be exactly the same as the `FRONTEND_URL` of Postiz.
Use ‘state’ parameter as ‘nonce’	`Disabled` (default)	No change is required for Postiz.
Access / Refresh / ID Token Lifetime, CORS	Empty	Default session based lifetimes are used. CORS is not required.

The path of the redirect URI is fixed by Postiz and it is /settings. A different path or a trailing slash causes a redirect URI mismatch after the sign-in.

If you also want users to start the sign-in from their Monosign portal, give the application a sign-in URL. Open the application, click Edit, go to the Login tab and enter the OAuth start address of Postiz in Login Url, then click Save.

Login tab of the application (1: Login tab, 2: Login Url, 3: Save)

Property	Value	Description
Login Url	`https://postiz.example.com/api/auth/oauth/GENERIC`	Postiz endpoint that starts the OAuth sign-in. When the user opens the Postiz tile in the Monosign portal, the browser goes to this address and Postiz redirects to Monosign.

3- Configuration Single Sign-On for Postiz

As we mentioned at the start, please check out the Postiz documentation first. Postiz is configured with environment variables only; there is no single sign-on screen in the Postiz interface. In the Docker Compose deployment add the following variables to the environment section of the postiz service and replace the placeholder values.

YAML

POSTIZ_GENERIC_OAUTH: 'true'
NEXT_PUBLIC_POSTIZ_OAUTH_DISPLAY_NAME: 'Monosign'
POSTIZ_OAUTH_URL: 'https://<monosign-host>'
POSTIZ_OAUTH_AUTH_URL: 'https://<monosign-host>/openid/authorize'
POSTIZ_OAUTH_TOKEN_URL: 'https://<monosign-host>/openid/token'
POSTIZ_OAUTH_USERINFO_URL: 'https://<monosign-host>/openid/userinfo'
POSTIZ_OAUTH_CLIENT_ID: '<client-id>'
POSTIZ_OAUTH_CLIENT_SECRET: '<client-secret>'

Variable	Value	Description
POSTIZ_GENERIC_OAUTH	`true`	Enables the generic OAuth sign-in. Any non-empty value enables it, including `false`. To turn it off delete the variable.
NEXT_PUBLIC_POSTIZ_OAUTH_DISPLAY_NAME	`Monosign`	Text of the button on the Postiz sign-in page (“Sign in with Monosign”).
POSTIZ_OAUTH_AUTH_URL	Auth Url	Monosign authorization endpoint.
POSTIZ_OAUTH_TOKEN_URL	Access Token Url	Monosign token endpoint.
POSTIZ_OAUTH_USERINFO_URL	User Info Url	Monosign UserInfo endpoint. Postiz reads the `email` and `sub` values from the response.
POSTIZ_OAUTH_CLIENT_ID / POSTIZ_OAUTH_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
FRONTEND_URL	`https://postiz.example.com`	Already part of the Postiz configuration. It must be the public address of Postiz; the redirect URI of the sign-in is `FRONTEND_URL/settings`.

The scope that Postiz sends is fixed in its code as openid profile email. The POSTIZ_OAUTH_SCOPE variable that appears in some examples is not read and cannot be used to change it.

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

Recreate the Postiz container so that the new variables are loaded.

Bash

cd /opt/postiz
docker compose up -d postiz

The frontend answers first. The backend of Postiz needs about one to two minutes to start, and the /api address returns 502 until it is ready. After that, the OAuth start address must answer with the Monosign sign-in address:

Bash

curl -s http://localhost:4007/api/auth/oauth/GENERIC
# https://<monosign-host>/openid/authorize?client_id=<client-id>&scope=openid+profile+email&response_type=code&state=login-…&redirect_uri=https%3A%2F%2Fpostiz.example.com%2Fsettings

4- Assign a User to the Postiz Application

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

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

Search and select the users who can sign in to Postiz, check the Expiration Date and click Save. You can select more than one user.

Property	Value	Description
User(s)	Selected users	Users who can sign in to Postiz with Monosign. Use the search box to find a user quickly.
Expiration Date	Default one year	The assignment expires on this date.

Monosign decides who can reach Postiz with the application assignments. DISABLE_REGISTRATION of Postiz closes the e-mail and password sign-up after the first organization is created, but it does not block the single sign-on users; a user who signs in with Monosign gets a Postiz account automatically.

Now try to log in to Postiz using Monosign SSO.

Open a new browser window (or a private window) and type the Postiz address, for example https://postiz.example.com.
Click Sign in with Monosign on the Postiz page.

Postiz sign-up page with the “Sign in with Monosign” button

Postiz redirects the browser to the Monosign sign-in page of the Postiz 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).

Monosign sign-in page of the Postiz application

After the sign-in Monosign redirects the browser back to Postiz (/settings). On the first sign-in Postiz continues with the sign-up form, shows the company name and creates the account of the user.

Postiz creates the account of the user after the Monosign sign-in

Troubleshooting

Symptom	Cause	Solution
The “Sign in with Monosign” button is not shown	`POSTIZ_GENERIC_OAUTH` is not set, or the container was not recreated.	Add the variables from step 3 and run `docker compose up -d postiz`.
`/api` answers 502 Bad Gateway right after the restart	The Postiz backend starts after the frontend.	Wait one to two minutes and try again.
Monosign shows a redirect URI error after the sign-in	The redirect URI that Postiz sends does not exactly match the Allowed Redirect URIs.	Make sure that `https://postiz.example.com/settings` is added in Monosign and that it uses the same host name as `FRONTEND_URL`.
The sign-in succeeds on Monosign but Postiz does not log the user in	The UserInfo response does not contain the `email` value that Postiz needs, or the Client Id/Secret is wrong.	Check the Client Id and Secret in the compose file. If the `email` claim is missing, add it in the Claim Mapping tab of the OIDC/OpenID settings with the value `{{Email}}`.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 4.
Single sign-on stays active after setting `POSTIZ_GENERIC_OAUTH` to `false`	Postiz only checks whether the variable has a value.	Delete the variable and recreate the container.
SAML sign-in is required	Postiz supports OAuth 2.0 / OpenID Connect only.	Use the OIDC/OpenID key of Monosign as described in this document.

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