Single Sign-On for Your Customer Messaging Platform: An OpenID Connect Guide for Support Teams

Single sign-on (SSO) for a customer messaging platform means your agents sign in with their company account at your identity provider, such as Microsoft Entra ID, Okta, Keycloak, AD FS or Google Workspace, instead of with a separate password. The standard behind it is OpenID Connect (OIDC). On an on-premise MonoChat installation you set it up once for the whole installation, limit it to your company’s e-mail domains, and can make it the only way to sign in.

Support teams have a particular reason to care. An agent’s account opens every WhatsApp, Instagram and Messenger conversation they can see: names, phone numbers, order details, sometimes health or payment questions. That account should follow the same rules as the rest of the company’s accounts, and it should stop working the day the person leaves.

Why the sign-in matters for a support team

Stolen or misused credentials are still the most common way into a company. Verizon’s 2025 Data Breach Investigations Report, which analysed 12,195 confirmed breaches, found that credential abuse (22%) and the exploitation of vulnerabilities (20%) were the leading initial attack vectors.

A messaging platform with its own passwords adds one more set of credentials to every agent: one more password to reuse, one more account to forget when someone leaves, one more login that your multi-factor and conditional access rules do not cover. With SSO the platform never sees the password. Your identity provider checks it, applies your MFA and access policies, and tells the platform who signed in.

How OpenID Connect sign-in works

OpenID Connect is an identity layer on top of OAuth 2.0. The flow MonoChat uses is the authorization code flow:

1. The agent clicks the SSO button on the sign-in page. MonoChat opens your identity provider’s sign-in page in a pop-up.
2. The agent signs in there, with your MFA and policies.
3. The identity provider sends the browser back to MonoChat with a one-time code.
4. The MonoChat server exchanges the code for an ID token, server to server. The tokens never pass through the browser.
5. MonoChat checks the ID token and signs the agent in.

The ID token is, in the words of the OpenID Connect specification, “a security token that contains Claims about the Authentication of an End-User”. MonoChat accepts it only when:

• it is signed with one of your identity provider’s keys, read from its discovery document (<issuer>/.well-known/openid-configuration) at every sign-in;
• its issuer (iss) is your issuer, its audience (aud) is MonoChat’s client ID and its expiry (exp) has not passed;
• it carries the nonce MonoChat sent with the request, which ties the token to this sign-in and blocks replays;
• it contains the person’s e-mail address, and the provider does not say that address is unverified.

The request also uses PKCE (S256) and a state value, and a sign-in request is valid for 10 minutes and can be used once.

Decide these five things before you turn SSO on

Decision	Options	What we suggest for a support team
Who may sign in	Every domain, or only your company’s e-mail domains	Limit it to your domains
What happens at a first sign-in	Create the account, or only accept invited people	Create accounts if your identity provider already controls who works there
Existing accounts	Link SSO at the first sign-in when the e-mail is verified, or after one password sign-in	Depends on whether your provider sends email_verified
Other sign-in methods	Keep passwords and social sign-in, or SSO only	SSO only, once everyone has linked SSO
Who can open new workspaces	Anyone with an account, or only people with the right role	Turn off open workspace creation in a company installation

Write these down before you change any setting. They are the questions your security team will ask, and the answers decide which settings you need.

Set up SSO on an on-premise MonoChat installation

SSO is set up for the whole installation in the server settings, not per workspace. The full reference is the single sign-on page in the help center; here is the short version.

1. Register MonoChat at your identity provider

Create a web application with a client secret, and give it:

• the redirect URI https://<your MonoChat domain>/api/oauth/oidc/redirect;
• the authorization code grant;
• the scopes openid email profile;
• client authentication with the secret sent as HTTP Basic (client_secret_basic).

Make sure the ID token includes the email claim, and note the client ID, the client secret and the issuer.

2. Copy the issuer exactly

The issuer is the issuer value in your provider’s discovery document. Typical forms:

Identity provider	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default or https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS 2016 or later	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Open <issuer>/.well-known/openid-configuration in a browser and copy the value character for character, including a trailing slash if it has one. MonoChat refuses every sign-in when the two differ, which is the most common reason a first test fails.

3. Add the settings and restart

The public part (issuer, client ID, redirect path, scopes and the button text) goes under public.oauth.oidc; the client secret goes under oauth.oidc and stays on the server. Two options there carry your decisions from the table above:

• autoCreateAccounts: true creates the MonoChat account at a person’s first SSO sign-in, even when sign-up is invitation-only;
• allowedEmailDomains: ["yourcompany.com"] refuses every address on another domain. For Google Workspace, MonoChat checks the Workspace domain of the account (the hd claim) instead of the e-mail address, because a personal Google account can use an address on any domain.

The button reads “Sign in with SSO” in each person’s language, or the label you set, such as “Sign in with Northwind SSO”.

4. Make SSO the only method, safely

When everyone has linked SSO, set the allowed sign-in methods (public.auth.methods) to ["oidc"]. The sign-in page then shows only the SSO button, and the server refuses password and social sign-in. Root super users can still sign in with their password at /auth/signin?fallback=1, so a down identity provider never locks the installation. To stop new SSO accounts from opening workspaces of their own, set public.disableTenantCreation to true.

5. Test four sign-ins

1. A person with an account: the pop-up closes and they are in.
2. A person without an account: the account is created, or refused if you did not turn on account creation.
3. A person on another domain: refused, if you limited domains.
4. A password sign-in with SSO-only on: refused, while the root fallback still works.

Existing agents: how accounts are linked

Most teams turn on SSO with agents who already have MonoChat accounts. MonoChat links SSO to an existing account with the same e-mail address in one of two ways:

• Automatically, at the first SSO sign-in, when the installation allows merging and the ID token says the address is verified (email_verified: true).
• After one password sign-in, in every other case: MonoChat asks the person to sign in with their password once and links SSO then. Accepting an invitation to a workspace links it too.

Microsoft Entra ID and AD FS do not send email_verified. With them, keep password sign-in allowed until everyone has linked SSO, or invite the people again, before you switch to SSO only.

SSO is the identity; roles are the access

Signing in gives a person an account, not access to your conversations. A MonoChat account can belong to several workspaces, and people sign in before they choose one. A person sees a workspace only after it invites them and gives them a role, and the role decides which channels, conversations and settings they reach. See team inbox roles and permissions for how to set those up.

That split is what an auditor will want to see:

• Joiner: the identity provider creates the person; a workspace admin invites them and picks the role.
• Mover: change the role or the workgroup in MonoChat; the sign-in does not change.
• Leaver: disable the person at the identity provider, and remove them from the workspace in MonoChat.

Limits to plan around

• The mobile app. The MonoChat Android and iOS app does not offer SSO yet. If SSO is the only sign-in method, agents cannot sign in on their phones, so keep another method for mobile users or plan for desktop-only shifts.
• Sign-out. Signing out of MonoChat does not sign the person out of the identity provider, and signing out there does not sign them out of MonoChat yet. Disabling a leaver at the identity provider stops new sign-ins; remove them from the workspace too.
• Network. People’s browsers must reach /api/oauth/oidc/authorize and the redirect path, and the MonoChat server must reach your provider’s discovery document, token endpoint and key set over HTTPS. If you also restrict the installation by IP, keep those paths in mind.

Where SSO fits in MonoChat

SSO is configured in the server settings of a whole installation, so today it belongs to on-premise MonoChat: the Enterprise option for teams that run the platform on their own servers, with their own LLM and vector database. The Enterprise page explains the on-premise option, and the security page covers role-based access, workspace isolation and certifications. For the data side of an AI rollout, see the AI chatbot privacy checklist.

To try the product itself first, the free Basic plan at app.monochat.ai gives you one agent and one channel.

Sources

• OpenID Connect Core 1.0, OpenID Foundation, opened 4 Nov 2026
• Verizon 2025 Data Breach Investigations Report announcement, opened 4 Nov 2026
• MonoChat help center: Single Sign-On for an On-Premise Installation, opened 4 Nov 2026
• MonoChat changelog 3.8.43, 2 Nov 2026