Single Sign-On for an On-Premise Installation

This page is for operators of an on-premise MonoChat installation. It explains how to let your staff sign in with your company's identity provider (IdP) through OpenID Connect (OIDC), for example Microsoft Entra ID, Okta, Keycloak, AD FS or Google Workspace.

Single sign-on is set up for the whole installation in the server settings, not per tenant. A MonoChat account can belong to several tenants, and people sign in before they choose one. Signing in gives an account, not access: a person still sees a tenant only after that tenant invites them and gives them a role.

How sign-in works

When someone clicks the SSO button on the sign-in page, MonoChat opens your IdP's sign-in page in a pop-up. After the person signs in there, the IdP sends the browser back to MonoChat with a one-time code. The MonoChat server exchanges the code for an ID token and checks it before it signs the person in:

• The IdP's endpoints and signing keys are read from its discovery document, <issuer>/.well-known/openid-configuration, at every sign-in.
• The sign-in uses the authorization code flow with PKCE (S256), a state and a nonce. A sign-in request is valid for 10 minutes and can be used once.
• The ID token must be signed with one of the IdP's keys and carry your issuer (iss), your client ID (aud), the request's nonce, and an expiry (exp) that has not passed.
• The ID token must contain the person's e-mail address (email). A sign-in is refused when the IdP says the address is not verified (email_verified: false).

1. Register MonoChat at your identity provider

Create an application (a client) for MonoChat at your IdP with these values:

Setting at the IdP	Value
Application type	Web application with a client secret (a confidential client)
Sign-in redirect URI	https://<your MonoChat domain>/api/oauth/oidc/redirect
Grant type	Authorization code
Scopes	openid email profile
Client authentication at the token endpoint	Client secret sent with HTTP Basic authentication (client_secret_basic)

Make sure the ID token contains the email claim. Note the client ID, the client secret and the issuer. The issuer is the issuer value in the IdP'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 its issuer value exactly, including a trailing / if it has one. MonoChat refuses to sign anyone in when the two differ.

2. Add the settings

Add the oidc blocks to the server settings and restart MonoChat. The public block goes under public.oauth, the secret block under oauth:

{
  "oauth": {
    "oidc": {
      "clientSecret": "<client secret>",
      "autoCreateAccounts": true,
      "allowedEmailDomains": ["company.com"]
    }
  },
  "public": {
    "oauth": {
      "oidc": {
        "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
        "clientId": "<client id>",
        "redirectPath": "/api/oauth/oidc/redirect",
        "scope": "openid email profile",
        "buttonLabel": "Sign in with Company SSO"
      }
    }
  }
}

Setting	What it does
public.oauth.oidc.issuer	The issuer from step 1
public.oauth.oidc.clientId	The client ID from step 1
public.oauth.oidc.redirectPath	The path of the redirect URI from step 1
public.oauth.oidc.scope	The scopes MonoChat asks for
public.oauth.oidc.buttonLabel	The text of the sign-in button. Empty shows "Sign in with SSO" in the person's language
oauth.oidc.clientSecret	The client secret. It stays on the server
oauth.oidc.autoCreateAccounts	true creates the MonoChat account at a person's first SSO sign-in, even when sign-up is invitation-only (public.disableSignup)
oauth.oidc.allowedEmailDomains	Only people whose e-mail address is on one of these domains may sign in through SSO. Leave it out to allow every domain

The SSO button then appears on the sign-in page.

Who can sign in

• New people. With autoCreateAccounts: true, a person's first SSO sign-in creates their account. Without it, the account is created only when public.disableSignup is off or the person signs in from an invitation.
• People who already have an account with the same e-mail address. With oauth.autoMerge: true, the first SSO sign-in links SSO to the existing account, but only when the ID token says the address is verified (email_verified: true). Otherwise, and always without autoMerge, MonoChat asks the person to sign in with their password once and links SSO to the account then; accepting an invitation to a workspace links it too. Microsoft Entra ID and AD FS do not send email_verified, so with them keep password sign-in allowed until everyone has linked SSO, or invite the people again.
• Allowed domains. With allowedEmailDomains, an address on any other domain is refused. For Google Workspace (issuer https://accounts.google.com), MonoChat checks the hd claim, the Workspace domain of the account, instead of the e-mail address, because a personal Google account can use an address on any domain.

Make SSO the only sign-in method

1. Set public.auth.methods to ["oidc"]. The sign-in page then shows only the SSO button, and the server refuses password and social sign-in.
2. Root super users (users with the root super role in the root tenant) can still sign in with their password at /auth/signin?fallback=1, so the installation is never locked out if the IdP is down.
3. To stop new SSO accounts from opening their own tenants, set public.disableTenantCreation to true. Only people with the right role in a tenant can then create tenants under it.

Network

• Keep /api/oauth/oidc/authorize and your redirectPath reachable for the people who sign in. Both are opened in their browser.
• The MonoChat server must reach your IdP's discovery document, token endpoint and key set (jwks_uri) over HTTPS.

Limits

• The MonoChat mobile app does not offer SSO yet. If you make SSO the only sign-in method, agents cannot sign in to the mobile app.
• Signing out of MonoChat does not sign the person out of the IdP, and signing out of the IdP does not sign them out of MonoChat yet.

Check your setup

1. Open the sign-in page and click the SSO button. Sign in at your IdP; the pop-up closes and you are signed in to MonoChat.
2. Sign in with a person who has no MonoChat account yet, and confirm the account is created (or refused, if you did not turn on autoCreateAccounts).
3. If you set allowedEmailDomains, try a person on another domain and confirm the sign-in is refused.
4. If you set public.auth.methods, confirm that a password sign-in is refused, and that a root super user can still sign in at /auth/signin?fallback=1.