Logon único para uma instalação on-premise

Esta página é para operadores de uma instalação on-premise do MonoChat. Ela explica como permitir que sua equipe entre com o provedor de identidade (IdP) da sua empresa por meio do OpenID Connect (OIDC), por exemplo Microsoft Entra ID, Okta, Keycloak, AD FS ou Google Workspace.

O logon único é configurado para toda a instalação nas configurações do servidor, não por organização. Uma conta do MonoChat pode pertencer a várias organizações, e as pessoas entram antes de escolher uma. Entrar dá uma conta, não acesso: uma pessoa só vê uma organização depois que essa organização a convida e lhe atribui uma função.

Como o login funciona

Quando alguém clica no botão SSO da página de login, o MonoChat abre a página de login do seu IdP em uma janela pop-up. Depois que a pessoa entra ali, o IdP devolve o navegador ao MonoChat com um código de uso único. O servidor do MonoChat troca o código por um token de ID e o verifica antes de conectar a pessoa:

• Os endpoints e as chaves de assinatura do IdP são lidos do documento de descoberta, <issuer>/.well-known/openid-configuration, a cada login.
• O login usa o fluxo de código de autorização com PKCE (S256), um state e um nonce. Uma solicitação de login vale por 10 minutos e pode ser usada uma vez.
• O token de ID precisa estar assinado com uma das chaves do IdP e conter seu emissor (iss), seu ID de cliente (aud), o nonce da solicitação e uma expiração (exp) que ainda não passou.
• O token de ID precisa conter o endereço de e-mail da pessoa (email). O login é recusado quando o IdP informa que o endereço não está verificado (email_verified: false).

1. Registre o MonoChat no seu provedor de identidade

Crie um aplicativo (um cliente) para o MonoChat no seu IdP com estes valores:

Configuração no IdP	Valor
Tipo de aplicativo	Aplicativo web com segredo do cliente (cliente confidencial)
URI de redirecionamento do login	https://<your MonoChat domain>/api/oauth/oidc/redirect
Tipo de concessão	Código de autorização
Escopos	openid email profile
Autenticação do cliente no endpoint de token	Segredo do cliente enviado com autenticação HTTP Basic (client_secret_basic)

Verifique se o token de ID contém a claim email. Anote o ID do cliente, o segredo do cliente e o emissor. O emissor é o valor issuer no documento de descoberta do IdP. Formatos comuns:

Provedor de identidade	Emissor (issuer)
Microsoft Entra ID	https://login.microsoftonline.com/<tenant id>/v2.0
Okta	https://<your Okta domain>/oauth2/default ou https://<your Okta domain>
Keycloak	https://<your Keycloak host>/realms/<realm>
AD FS (2016 ou posterior)	https://<your AD FS host>/adfs
Google Workspace	https://accounts.google.com

Abra <issuer>/.well-known/openid-configuration em um navegador e copie o valor issuer exatamente, incluindo uma / final se houver. O MonoChat não conecta ninguém quando os dois são diferentes.

2. Adicione as configurações

Adicione os blocos oidc às configurações do servidor e reinicie o MonoChat. O bloco público fica em public.oauth, e o bloco secreto em 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"
      }
    }
  }
}

Configuração	O que faz
public.oauth.oidc.issuer	O emissor do passo 1
public.oauth.oidc.clientId	O ID do cliente do passo 1
public.oauth.oidc.redirectPath	O caminho do URI de redirecionamento do passo 1
public.oauth.oidc.scope	Os escopos que o MonoChat solicita
public.oauth.oidc.buttonLabel	O texto do botão de login. Vazio mostra "Entrar com SSO" no idioma da pessoa
oauth.oidc.clientSecret	O segredo do cliente. Ele fica no servidor
oauth.oidc.autoCreateAccounts	true cria a conta do MonoChat no primeiro login SSO de uma pessoa, mesmo quando o cadastro é só por convite (public.disableSignup)
oauth.oidc.allowedEmailDomains	Só pessoas com endereço de e-mail em um destes domínios podem entrar por SSO. Deixe de fora para permitir todos os domínios

O botão SSO passa então a aparecer na página de login.

Quem pode entrar

• Pessoas novas. Com autoCreateAccounts: true, o primeiro login SSO de uma pessoa cria a conta dela. Sem isso, a conta só é criada quando public.disableSignup está desativado ou a pessoa entra a partir de um convite.
• Pessoas que já têm uma conta com o mesmo e-mail. Com oauth.autoMerge: true, o primeiro login SSO vincula o SSO à conta existente, mas só quando o token de ID informa que o endereço está verificado (email_verified: true). Nos demais casos, e sempre sem autoMerge, o MonoChat pede que a pessoa entre uma vez com a senha e então vincula o SSO à conta; aceitar um convite para uma organização também faz o vínculo. Microsoft Entra ID e AD FS não enviam email_verified, então, com eles, mantenha o login com senha permitido até que todos tenham vinculado o SSO, ou convide as pessoas de novo.
• Domínios permitidos. Com allowedEmailDomains, um endereço de qualquer outro domínio é recusado. No Google Workspace (emissor https://accounts.google.com), o MonoChat verifica a claim hd, o domínio do Workspace da conta, em vez do endereço de e-mail, porque uma conta pessoal do Google pode usar um endereço de qualquer domínio.

Torne o SSO o único método de login

1. Defina public.auth.methods como ["oidc"]. A página de login passa a mostrar só o botão SSO, e o servidor recusa login com senha e por redes sociais.
2. Usuários root super (usuários com a função root super na organização raiz) ainda podem entrar com a senha em /auth/signin?fallback=1, para que a instalação nunca fique bloqueada se o IdP estiver fora do ar.
3. Para impedir que novas contas SSO abram as próprias organizações, defina public.disableTenantCreation como true. Então só pessoas com a função adequada em uma organização podem criar organizações abaixo dela.

Rede

• Mantenha /api/oauth/oidc/authorize e o seu redirectPath acessíveis para as pessoas que entram. Os dois são abertos no navegador delas.
• O servidor do MonoChat precisa alcançar por HTTPS o documento de descoberta, o endpoint de token e o conjunto de chaves (jwks_uri) do seu IdP.

Limitações

• O aplicativo móvel do MonoChat ainda não oferece SSO. Se você tornar o SSO o único método de login, os agentes não conseguirão entrar no aplicativo móvel.
• Sair do MonoChat não desconecta a pessoa do IdP, e sair do IdP ainda não a desconecta do MonoChat.

Verifique a configuração

1. Abra a página de login e clique no botão SSO. Entre no seu IdP; a janela pop-up se fecha e você fica conectado ao MonoChat.
2. Entre com uma pessoa que ainda não tem conta no MonoChat e confirme que a conta é criada (ou recusada, se você não ativou autoCreateAccounts).
3. Se você definiu allowedEmailDomains, tente com uma pessoa de outro domínio e confirme que o login é recusado.
4. Se você definiu public.auth.methods, confirme que um login com senha é recusado e que um usuário root super ainda consegue entrar em /auth/signin?fallback=1.