Single sign-on voor een on-premise installatie

Deze pagina is bedoeld voor beheerders van een on-premise MonoChat-installatie. Ze legt uit hoe uw medewerkers inloggen met de identiteitsprovider (IdP) van uw bedrijf via OpenID Connect (OIDC), bijvoorbeeld Microsoft Entra ID, Okta, Keycloak, AD FS of Google Workspace.

Single sign-on stelt u in voor de hele installatie in de serverinstellingen, niet per organisatie. Een MonoChat-account kan bij meerdere organisaties horen, en men logt in voordat men er een kiest. Inloggen geeft een account, geen toegang: iemand ziet een organisatie pas nadat die organisatie hem heeft uitgenodigd en een rol heeft gegeven.

Hoe inloggen werkt

Wanneer iemand op de inlogpagina op de SSO-knop klikt, opent MonoChat de inlogpagina van uw IdP in een pop-up. Nadat de persoon daar is ingelogd, stuurt de IdP de browser terug naar MonoChat met een eenmalige code. De MonoChat-server wisselt de code in voor een ID-token en controleert dat voordat de persoon wordt ingelogd:

• De endpoints en ondertekeningssleutels van de IdP worden bij elke aanmelding gelezen uit het discovery-document, <issuer>/.well-known/openid-configuration.
• Het inloggen gebruikt de authorization-code-flow met PKCE (S256), een state en een nonce. Een inlogverzoek is 10 minuten geldig en kan één keer worden gebruikt.
• Het ID-token moet ondertekend zijn met een van de sleutels van de IdP en uw issuer (iss), uw client-ID (aud), de nonce van het verzoek en een vervaltijd (exp) bevatten die nog niet is verstreken.
• Het ID-token moet het e-mailadres van de persoon bevatten (email). Inloggen wordt geweigerd wanneer de IdP aangeeft dat het adres niet is geverifieerd (email_verified: false).

1. Registreer MonoChat bij uw identiteitsprovider

Maak bij uw IdP een applicatie (een client) voor MonoChat aan met deze waarden:

Instelling bij de IdP	Waarde
Type applicatie	Webapplicatie met een client secret (een vertrouwelijke client)
Redirect-URI voor inloggen	https://<your MonoChat domain>/api/oauth/oidc/redirect
Granttype	Authorization code
Scopes	openid email profile
Clientauthenticatie bij het token-endpoint	Client secret verzonden met HTTP Basic-authenticatie (client_secret_basic)

Zorg dat het ID-token de claim email bevat. Noteer de client-ID, het client secret en de issuer. De issuer is de waarde issuer in het discovery-document van de IdP. Gangbare vormen:

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

Open <issuer>/.well-known/openid-configuration in een browser en kopieer de waarde issuer exact, inclusief een afsluitende / als die er is. MonoChat logt niemand in wanneer de twee verschillen.

2. Voeg de instellingen toe

Voeg de oidc-blokken toe aan de serverinstellingen en herstart MonoChat. Het openbare blok komt onder public.oauth, het geheime blok onder 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"
      }
    }
  }
}

Instelling	Wat het doet
public.oauth.oidc.issuer	De issuer uit stap 1
public.oauth.oidc.clientId	De client-ID uit stap 1
public.oauth.oidc.redirectPath	Het pad van de redirect-URI uit stap 1
public.oauth.oidc.scope	De scopes die MonoChat aanvraagt
public.oauth.oidc.buttonLabel	De tekst van de inlogknop. Leeg toont "Inloggen met SSO" in de taal van de persoon
oauth.oidc.clientSecret	Het client secret. Het blijft op de server
oauth.oidc.autoCreateAccounts	true maakt het MonoChat-account aan bij de eerste SSO-aanmelding van iemand, ook als registreren alleen op uitnodiging kan (public.disableSignup)
oauth.oidc.allowedEmailDomains	Alleen mensen met een e-mailadres in een van deze domeinen mogen via SSO inloggen. Laat het weg om elk domein toe te staan

De SSO-knop verschijnt dan op de inlogpagina.

Wie kan inloggen

• Nieuwe mensen. Met autoCreateAccounts: true maakt de eerste SSO-aanmelding van iemand zijn account aan. Zonder deze instelling wordt het account alleen aangemaakt als public.disableSignup uit staat of de persoon inlogt vanuit een uitnodiging.
• Mensen die al een account met hetzelfde e-mailadres hebben. Met oauth.autoMerge: true koppelt de eerste SSO-aanmelding SSO aan het bestaande account, maar alleen wanneer het ID-token aangeeft dat het adres is geverifieerd (email_verified: true). Anders, en zonder autoMerge altijd, vraagt MonoChat de persoon één keer met het wachtwoord in te loggen en koppelt SSO dan aan het account; ook het accepteren van een uitnodiging voor een organisatie koppelt het. Microsoft Entra ID en AD FS sturen geen email_verified mee, dus laat bij hen inloggen met wachtwoord toegestaan totdat iedereen SSO heeft gekoppeld, of nodig de mensen opnieuw uit.
• Toegestane domeinen. Met allowedEmailDomains wordt een adres in elk ander domein geweigerd. Bij Google Workspace (issuer https://accounts.google.com) controleert MonoChat de claim hd, het Workspace-domein van het account, in plaats van het e-mailadres, omdat een persoonlijk Google-account een adres in elk domein kan gebruiken.

Maak SSO de enige inlogmethode

1. Stel public.auth.methods in op ["oidc"]. De inlogpagina toont dan alleen de SSO-knop en de server weigert inloggen met wachtwoord en via sociale accounts.
2. Root-superusers (gebruikers met de rol root super in de root-organisatie) kunnen nog steeds met hun wachtwoord inloggen op /auth/signin?fallback=1, zodat de installatie nooit wordt buitengesloten als de IdP niet beschikbaar is.
3. Om te voorkomen dat nieuwe SSO-accounts eigen organisaties openen, stelt u public.disableTenantCreation in op true. Alleen mensen met de juiste rol in een organisatie kunnen daaronder dan organisaties aanmaken.

Netwerk

• Houd /api/oauth/oidc/authorize en uw redirectPath bereikbaar voor de mensen die inloggen. Beide worden in hun browser geopend.
• De MonoChat-server moet het discovery-document, het token-endpoint en de sleutelset (jwks_uri) van uw IdP via HTTPS kunnen bereiken.

Beperkingen

• De mobiele MonoChat-app biedt nog geen SSO. Als u SSO de enige inlogmethode maakt, kunnen agents niet inloggen in de mobiele app.
• Uitloggen bij MonoChat logt de persoon niet uit bij de IdP, en uitloggen bij de IdP logt hem nog niet uit bij MonoChat.

Controleer uw configuratie

1. Open de inlogpagina en klik op de SSO-knop. Log in bij uw IdP; de pop-up sluit en u bent ingelogd bij MonoChat.
2. Log in met iemand die nog geen MonoChat-account heeft en controleer dat het account wordt aangemaakt (of geweigerd, als u autoCreateAccounts niet hebt ingeschakeld).
3. Als u allowedEmailDomains hebt ingesteld, probeer het met iemand uit een ander domein en controleer dat het inloggen wordt geweigerd.
4. Als u public.auth.methods hebt ingesteld, controleer dan dat inloggen met wachtwoord wordt geweigerd en dat een root-superuser nog kan inloggen op /auth/signin?fallback=1.