Single sign-on per un'installazione on-premise

Questa pagina è per chi gestisce un'installazione MonoChat on-premise. Spiega come consentire al personale di accedere con il provider di identità (IdP) dell'azienda tramite OpenID Connect (OIDC), ad esempio Microsoft Entra ID, Okta, Keycloak, AD FS o Google Workspace.

Il single sign-on si configura per l'intera installazione nelle impostazioni del server, non per singola organizzazione. Un account MonoChat può appartenere a più organizzazioni, e si accede prima di sceglierne una. L'accesso dà un account, non i permessi: una persona vede un'organizzazione solo dopo che questa l'ha invitata e le ha assegnato un ruolo.

Come funziona l'accesso

Quando qualcuno fa clic sul pulsante SSO nella pagina di accesso, MonoChat apre la pagina di accesso dell'IdP in un pop-up. Dopo che la persona ha effettuato l'accesso, l'IdP rimanda il browser a MonoChat con un codice monouso. Il server MonoChat scambia il codice con un ID token e lo verifica prima di far accedere la persona:

• Gli endpoint e le chiavi di firma dell'IdP vengono letti a ogni accesso dal suo documento di discovery, <issuer>/.well-known/openid-configuration.
• L'accesso usa il flusso authorization code con PKCE (S256), uno state e un nonce. Una richiesta di accesso è valida per 10 minuti e si può usare una sola volta.
• L'ID token deve essere firmato con una delle chiavi dell'IdP e contenere il tuo issuer (iss), il tuo client ID (aud), il nonce della richiesta e una scadenza (exp) non ancora superata.
• L'ID token deve contenere l'indirizzo e-mail della persona (email). L'accesso viene rifiutato quando l'IdP indica che l'indirizzo non è verificato (email_verified: false).

1. Registra MonoChat presso il tuo provider di identità

Crea nell'IdP un'applicazione (un client) per MonoChat con questi valori:

Impostazione nell'IdP	Valore
Tipo di applicazione	Applicazione web con client secret (client confidenziale)
URI di reindirizzamento dell'accesso	https://<your MonoChat domain>/api/oauth/oidc/redirect
Tipo di grant	Authorization code
Scope	openid email profile
Autenticazione del client all'endpoint del token	Client secret inviato con autenticazione HTTP Basic (client_secret_basic)

Assicurati che l'ID token contenga la claim email. Annota client ID, client secret e issuer. L'issuer è il valore issuer nel documento di discovery dell'IdP. Forme tipiche:

Provider di identità	Issuer
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default oppure https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS (2016 o successivo)	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Apri <issuer>/.well-known/openid-configuration in un browser e copia il valore issuer esattamente, compresa la / finale se presente. MonoChat non fa accedere nessuno quando i due valori sono diversi.

2. Aggiungi le impostazioni

Aggiungi i blocchi oidc alle impostazioni del server e riavvia MonoChat. Il blocco pubblico va sotto public.oauth, quello segreto sotto 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"
      }
    }
  }
}

Impostazione	Cosa fa
public.oauth.oidc.issuer	L'issuer del passaggio 1
public.oauth.oidc.clientId	Il client ID del passaggio 1
public.oauth.oidc.redirectPath	Il percorso dell'URI di reindirizzamento del passaggio 1
public.oauth.oidc.scope	Gli scope richiesti da MonoChat
public.oauth.oidc.buttonLabel	Il testo del pulsante di accesso. Se vuoto mostra "Accedi con SSO" nella lingua della persona
oauth.oidc.clientSecret	Il client secret. Resta sul server
oauth.oidc.autoCreateAccounts	true crea l'account MonoChat al primo accesso SSO di una persona, anche quando la registrazione è solo su invito (public.disableSignup)
oauth.oidc.allowedEmailDomains	Solo le persone con un indirizzo e-mail in uno di questi domini possono accedere tramite SSO. Omettilo per consentire tutti i domini

Il pulsante SSO compare quindi nella pagina di accesso.

Chi può accedere

• Persone nuove. Con autoCreateAccounts: true, il primo accesso SSO di una persona crea il suo account. Senza questa impostazione, l'account viene creato solo se public.disableSignup è disattivato o se la persona accede da un invito.
• Persone che hanno già un account con lo stesso indirizzo e-mail. Con oauth.autoMerge: true, il primo accesso SSO collega l'SSO all'account esistente, ma solo quando l'ID token indica che l'indirizzo è verificato (email_verified: true). Altrimenti, e sempre senza autoMerge, MonoChat chiede alla persona di accedere una volta con la password e poi collega l'SSO all'account; anche accettare un invito a un'organizzazione lo collega. Microsoft Entra ID e AD FS non inviano email_verified, quindi con loro lascia consentito l'accesso con password finché tutti non hanno collegato l'SSO, oppure invita di nuovo le persone.
• Domini consentiti. Con allowedEmailDomains, un indirizzo di qualsiasi altro dominio viene rifiutato. Per Google Workspace (issuer https://accounts.google.com), MonoChat controlla la claim hd, il dominio Workspace dell'account, invece dell'indirizzo e-mail, perché un account Google personale può usare un indirizzo di qualsiasi dominio.

Rendi l'SSO l'unico metodo di accesso

1. Imposta public.auth.methods su ["oidc"]. La pagina di accesso mostra quindi solo il pulsante SSO e il server rifiuta l'accesso con password e con i social.
2. Gli utenti root super (con il ruolo root super nell'organizzazione radice) possono comunque accedere con la password su /auth/signin?fallback=1, così l'installazione non resta mai bloccata se l'IdP non è disponibile.
3. Per impedire ai nuovi account SSO di aprire proprie organizzazioni, imposta public.disableTenantCreation su true. Solo chi ha il ruolo adatto in un'organizzazione potrà allora crearne altre al suo interno.

Rete

• Mantieni /api/oauth/oidc/authorize e il tuo redirectPath raggiungibili per le persone che accedono. Entrambi si aprono nel loro browser.
• Il server MonoChat deve raggiungere via HTTPS il documento di discovery, l'endpoint del token e il set di chiavi (jwks_uri) dell'IdP.

Limiti

• L'app mobile MonoChat non offre ancora l'SSO. Se rendi l'SSO l'unico metodo di accesso, gli agenti non possono accedere all'app mobile.
• Uscire da MonoChat non fa uscire la persona dall'IdP, e uscire dall'IdP non la fa ancora uscire da MonoChat.

Verifica la configurazione

1. Apri la pagina di accesso e fai clic sul pulsante SSO. Accedi nell'IdP; il pop-up si chiude e hai effettuato l'accesso a MonoChat.
2. Accedi con una persona che non ha ancora un account MonoChat e verifica che l'account venga creato (o rifiutato, se non hai attivato autoCreateAccounts).
3. Se hai impostato allowedEmailDomains, prova con una persona di un altro dominio e verifica che l'accesso venga rifiutato.
4. Se hai impostato public.auth.methods, verifica che l'accesso con password venga rifiutato e che un utente root super possa ancora accedere su /auth/signin?fallback=1.