Typebot OIDC Integration

This document explains how to implement Monosign with Typebot, the open-source chatbot builder. It covers Single Sign-On with OpenID Connect (OIDC), which is built into Typebot as the Custom OAuth provider. Typebot reads the Monosign addresses from the OIDC discovery document and uses the Authorization Code flow with PKCE, so the OIDC/OpenID access key of Monosign is used. Before you continue, it is better to read the Typebot configuration documentation (opens in a new tab).

This configuration was tested with Typebot 3.19.1 (self-hosted). If your Typebot version or deployment type is different, please check the Typebot documentation.

Typebot supports OpenID Connect through one custom provider and the ready-made Google, GitHub, GitLab, Facebook, Azure AD and Keycloak logins. SAML is not available. There is no single sign-on screen in the Typebot interface; the provider is configured with environment variables of the builder.

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

Typebot is open source under the Functional Source License (FSL-1.1, which becomes Apache 2.0 after two years) and can be self-hosted for your own use. Single sign-on with the custom provider is not limited by a license 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 Typebot application
Configuration Single Sign-On for Typebot
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.

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

Typebot creates an account and a workspace for every Monosign user who signs in for the first time (unless DISABLE_SIGNUP=true is set; invited users can still sign up). 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 Typebot application are provided as follows:

Monosign value	Example	Used in Typebot as
Client Id	`<client-id>`	`CUSTOM_OAUTH_CLIENT_ID`
Client Secret	`<client-secret>`	`CUSTOM_OAUTH_CLIENT_SECRET`
Configuration Url	`https://<monosign-host>/.well-known/openid-configuration`	`CUSTOM_OAUTH_ISSUER`. Typebot needs the address without the `.well-known/openid-configuration` part, as the issuer, for example `https://<monosign-host>/`. Keep the slash at the end, because the issuer of Monosign has it. Typebot 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 Typebot to Allowed Redirect URIs, then press Update.

Property	Value	Description
Allowed Redirect URIs	`https://<typebot-address>/api/auth/callback/custom-oauth`	The address where Monosign sends the user back after sign-in. The path `/api/auth/callback/custom-oauth` is fixed by Typebot (the identifier of the provider is `custom-oauth`). Use the public (HTTPS) address of the Typebot builder; it must be the same as `NEXTAUTH_URL` of step 4.
Scope	Optional	Typebot requests `openid profile email` by itself (`CUSTOM_OAUTH_SCOPE`), so the field can stay empty.
Other fields	Empty / default	The other fields (Signing Key, Issuer, Audience, Resource, token lifetimes, CORS, Initiate Login Url) are not needed. Do not enter the callback address in the Resource field.

Typebot reads the user from the claims sub, name and email of the ID token. Monosign returns them by default, so a claim mapping is not required. The claim id, which is the default of Typebot, does not exist in an OIDC token; set CUSTOM_OAUTH_USER_ID_PATH=sub in step 4.

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

4- Configuration Single Sign-On for Typebot

As we mentioned at the start, please check out the Typebot documentation first. Typebot is configured with environment variables of the builder. Add the following variables to the environment of the Typebot builder, replace the placeholder values and restart (recreate) the builder so that the new variables are loaded.

NEXTAUTH_URL=https://<typebot-host-name>
CUSTOM_OAUTH_NAME=Monosign
CUSTOM_OAUTH_ISSUER=https://<monosign-host>/
CUSTOM_OAUTH_CLIENT_ID=<client-id>
CUSTOM_OAUTH_CLIENT_SECRET=<client-secret>
CUSTOM_OAUTH_USER_ID_PATH=sub

Variable	Value	Description
NEXTAUTH_URL	`https://<typebot-host-name>`	Public HTTPS address of the builder. The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2. When Typebot is behind a reverse proxy, the proxy must send `X-Forwarded-Proto: https`.
CUSTOM_OAUTH_NAME	`Monosign`	Name of the provider. The sign-in button shows it as Continue with Monosign.
CUSTOM_OAUTH_ISSUER	`https://<monosign-host>/`	Issuer of Monosign. The custom provider is enabled only when it is set. Keep the slash at the end.
CUSTOM_OAUTH_CLIENT_ID / CUSTOM_OAUTH_CLIENT_SECRET	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step.
CUSTOM_OAUTH_USER_ID_PATH	`sub`	Required for Monosign. Claim that identifies the user. The default of Typebot is `id`, which an OIDC token does not contain.
CUSTOM_OAUTH_USER_NAME_PATH / _USER_EMAIL_PATH	`name` / `email` (default)	Optional. Claims of the user name and the e-mail address. The e-mail address is required.
CUSTOM_OAUTH_SCOPE	`openid profile email` (default)	Optional. Scopes that Typebot requests.
CUSTOM_OAUTH_USE_USERINFO	`false` (default)	Optional. When `true`, the claims come from the UserInfo endpoint instead of the ID token.
DISABLE_SIGNUP	`false` (default)	Optional. When `true`, new users cannot sign up, also not through Monosign. Only invited users and existing accounts can sign in.

The environment of the builder contains the client secret. Keep the file that holds it private (for example chmod 600) and do not store it in a shared repository.

5- Sign In Test

Now try to log in to Typebot using Monosign SSO. Open a new browser window (or a private window) and type the address of the Typebot builder. The sign-in page of Typebot shows the Continue with Monosign button.

Click the Continue 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 Typebot (/api/auth/callback/custom-oauth). At the first sign-in Typebot creates the account and a workspace named after the user, and opens the dashboard.

Troubleshooting

Symptom	Cause	Solution
The Continue with Monosign button is not shown	`CUSTOM_OAUTH_ISSUER` is not set, so the custom provider is disabled, or the builder was not restarted after the change.	Set the variables (step 4) and recreate the builder.
Monosign shows a redirect URI error	The redirect address that Typebot sends does not exactly match the Allowed Redirect URIs, for example because `NEXTAUTH_URL` 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://<typebot-address>/api/auth/callback/custom-oauth` to Allowed Redirect URIs in Monosign (step 2) and set `NEXTAUTH_URL` to the same public HTTPS address.
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), `CUSTOM_OAUTH_USER_ID_PATH` is not `sub`, or Typebot cannot reach Monosign.	Copy the values again from the Monosign access key (step 1), use the issuer with the slash at the end, set `CUSTOM_OAUTH_USER_ID_PATH=sub` and check the builder log and the network access to Monosign.
The sign-in fails because the e-mail address is missing	The ID token has no `email` claim.	Set `Profile Access Type` to All (step 1) and keep the scope `email`; set `CUSTOM_OAUTH_USE_USERINFO=true` if the claim is only in the user information.
A new user cannot sign in	`DISABLE_SIGNUP=true` is set, or the user is not assigned to the application.	Remove the variable or invite the user in Typebot, and assign the user in step 3.

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