ChiefOnboarding OIDC Integration

This document explains how to implement Monosign with ChiefOnboarding, the open-source employee onboarding platform. It covers Single Sign-On with OpenID Connect (OIDC), which ChiefOnboarding provides through the django-allauth library. ChiefOnboarding 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 ChiefOnboarding OIDC documentation.

This configuration is done with the ChiefOnboarding Docker image (chiefonboarding/chiefonboarding:latest, October 2026) and postgres:16 running on Docker Compose. If your ChiefOnboarding version or deployment type is different, please check the ChiefOnboarding documentation.

ChiefOnboarding supports OpenID Connect only. SAML is not available in ChiefOnboarding. There is no single sign-on screen in the ChiefOnboarding interface; the provider is configured with environment variables.

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

ChiefOnboarding is not in the application catalog, so click Create from scratch, fill in the application details on the Application tab and click Next.

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

Property	Value	Description
Name	`Chiefonboarding`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	ChiefOnboarding is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the ChiefOnboarding address so users can open the application from their Monosign portal (see the note in 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.

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). ChiefOnboarding 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 Chiefonboarding 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 Chiefonboarding application are provided as follows:

Monosign value	Example	Used in ChiefOnboarding as
Client Id	`<client-id>`	`client_id` in `SSO_PROVIDERS`
Client Secret	`<client-secret>`	`secret` in `SSO_PROVIDERS`
Configuration Url (without the `/.well-known/openid-configuration` part)	`https://<monosign-host>`	`server_url` in `SSO_PROVIDERS`. ChiefOnboarding 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 ChiefOnboarding to Allowed Redirect URIs.

OIDC/OpenID Settings (Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://<chiefonboarding-address>/accounts/oidc/monosign/login/callback/`	The address where Monosign sends the user back after sign-in. The path is `/accounts/oidc/<provider_id>/login/callback/` and `monosign` is the `provider_id` that is used in step 4, so both must be the same. Keep the trailing slash. Use the public (HTTPS) address of ChiefOnboarding; 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 for ChiefOnboarding.
Token lifetimes, CORS	Empty	Default values are used.

ChiefOnboarding reads the user information from the Monosign ID token and UserInfo endpoint: sub, the email address and the name. Monosign returns these claims by default, so a claim mapping is not required. The e-mail address is required. If you want the first and last name to be filled in as well, add the claims given_name ({{Profile.FirstName}}) and family_name ({{Profile.LastName}}) on the Claim Mapping tab and click Update.

3- Assign a User to the ChiefOnboarding Application

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

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

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

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

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

4- Configuration Single Sign-On for ChiefOnboarding

As we mentioned at the start, please check out the ChiefOnboarding documentation first. ChiefOnboarding is configured with environment variables. In the Docker Compose deployment add the following variables to the environment file of the app service (for example the .env file that is used with env_file) and replace the placeholder values.

Bash

ALLOWED_HOSTS=<chiefonboarding-host-name>
BASE_URL=https://<chiefonboarding-host-name>
ALLAUTH_PROVIDERS=openid_connect
SSO_AUTO_CREATE_USER=True
SSO_PROVIDERS='{"openid_connect": {"APPS": [{"provider_id": "monosign", "name": "Monosign", "client_id": "<client-id>", "secret": "<client-secret>", "settings": {"server_url": "https://<monosign-host>", "VERIFIED_EMAIL": True}}]}}'

Variable	Value	Description
ALLOWED_HOSTS / BASE_URL	Host name / public HTTPS address	The host name that users type in the browser. ChiefOnboarding answers only these host names and uses `BASE_URL` to build the redirect address and to trust the origin of the sign-in form.
ALLAUTH_PROVIDERS	`openid_connect`	Enables the generic OpenID Connect provider of `django-allauth`.
SSO_AUTO_CREATE_USER	`True`	Creates the user automatically at the first sign-in. When it is not `True`, only users that already exist in ChiefOnboarding (same e-mail address) can sign in.
SSO_PROVIDERS	Provider definition	The value is read as a Python dictionary, so write `True` with a capital T and keep the whole value in single quotes.
provider_id	`monosign`	Becomes part of the callback address (`/accounts/oidc/monosign/login/callback/`). It must match the Allowed Redirect URI in Monosign.
name	`Monosign`	Text of the button on the sign-in page (“Log in with Monosign”).
client_id / secret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
server_url	`https://<monosign-host>`	Address of Monosign. ChiefOnboarding reads `/.well-known/openid-configuration` from it.
VERIFIED_EMAIL	`True`	ChiefOnboarding accepts the e-mail address only when the OIDC server returns `email_verified`. With this setting the e-mail address returned by Monosign is accepted as verified.

The role of a new user comes from the optional variables OIDC_ROLE_PATH_IN_RETURN, OIDC_ROLE_ADMIN_PATTERN, OIDC_ROLE_MANAGER_PATTERN and OIDC_ROLE_NEW_HIRE_PATTERN, which read a group claim from the token. When they are not set, every new user created by single sign-on gets the role Other and sees only the Colleagues and Resources pages. To keep the administrator role, create the administrator first (the first account can be created with the ACCOUNT_EMAIL and ACCOUNT_PASSWORD variables) and use the same e-mail address in Monosign; ChiefOnboarding links the single sign-on account to the existing user with the same e-mail address.

The environment file contains the client secret, the secret key of the application and the database password. Restrict its permissions (for example chmod 600) and do not store it in a shared repository. Because the e-mail address links an identity provider account to an existing user, use single sign-on only with an identity provider that you trust (Monosign) and do not leave VERIFIED_EMAIL on for a provider that does not check the e-mail address.

Recreate the ChiefOnboarding container so that the new variables are loaded:

Bash

cd <chiefonboarding-compose-directory>
docker compose up -d

The sign-in page must now show the local e-mail and password form and the “Log in with Monosign” button.

Now try to log in to ChiefOnboarding using Monosign SSO.

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

Click Log in with Monosign. ChiefOnboarding redirects the browser to the Monosign sign-in page of the Chiefonboarding 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 ChiefOnboarding. ChiefOnboarding creates the account on the first sign-in and shows the message that you are signed in. A new user with the role Other opens the Colleagues page, and the signed-in user is shown at the top right.

User logged in to ChiefOnboarding through Monosign SSO (“Successfully signed in” message and the Colleagues page)

When you open ChiefOnboarding from the Monosign portal, a link to the single sign-on address (https://<chiefonboarding-address>/accounts/oidc/monosign/login/?process=login) opens a confirmation page of ChiefOnboarding and you click Continue once. The sign-in is started with a form (POST request), so Monosign cannot start it directly with a link. If you enter only the ChiefOnboarding address as the Url of the application, the user opens the sign-in page and clicks Log in with Monosign.

Troubleshooting

Symptom	Cause	Solution
The “Log in with Monosign” button is not shown	`ALLAUTH_PROVIDERS` or `SSO_PROVIDERS` is missing, or the container was not recreated.	Set the variables and run `docker compose up -d`.
The container stops at the start with the message “You need to configure OIDC differently”	The old variable `OIDC_CLIENT_ID` is still set. ChiefOnboarding no longer uses it.	Remove `OIDC_CLIENT_ID` (and the other old `OIDC_` connection variables) and use `SSO_PROVIDERS` as in step 4.
Monosign shows a redirect URI error	The redirect URI that ChiefOnboarding sends does not exactly match the Allowed Redirect URIs.	Add `https://<chiefonboarding-address>/accounts/oidc/monosign/login/callback/` in Monosign (step 2). Check the trailing slash and that `monosign` is the same as `provider_id`.
The sign-in at Monosign succeeded, but ChiefOnboarding does not complete the login	Monosign did not return `email_verified`, so ChiefOnboarding does not accept the e-mail address.	Add `"VERIFIED_EMAIL": True` to the `settings` of the provider (step 4) and recreate the container.
The sign-in is refused for a user who does not exist in ChiefOnboarding	`SSO_AUTO_CREATE_USER` is not `True`.	Set `SSO_AUTO_CREATE_USER=True`, or create the user in ChiefOnboarding first with the same e-mail address.
The user signs in but sees only the Colleagues page	No role mapping is set, so the new user gets the role Other.	Create the administrator in ChiefOnboarding first and use the same e-mail address, or configure the `OIDC_ROLE_*` variables with a group claim.
ChiefOnboarding answers 400 Bad Request for the address	The host name is not in `ALLOWED_HOSTS`.	Add the host name that is used in the browser to `ALLOWED_HOSTS` and recreate the container.
The sign-in form returns a CSRF error behind a reverse proxy	The proxy does not send `X-Forwarded-Proto: https`, or `BASE_URL` does not match the address in the browser.	Send the `X-Forwarded-Proto` header from the proxy and set `BASE_URL` to the public HTTPS 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	ChiefOnboarding supports OpenID Connect only.	Use the OIDC integration in this document.

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