Provisionar usuários com SCIM

Use este guia quando você quiser controle de ciclo de vida — o desligamento de uma pessoa precisa revogar o acesso automaticamente, e não apenas bloquear logins futuros. O SCIM é o protocolo de push que os IdPs (Okta, Entra ID e outros) usam exatamente para isso.

Pré-requisitos

• SSO já funcionando (o tutorial de SSO ou o guia do OIDC),
• um servidor que o IdP consiga alcançar por HTTPS — as chamadas do SCIM partem do IdP, não do navegador do usuário. Use o túnel integrado (Configurações → Servidor → Conexão e status → Compartilhar este servidor → Cloudflared/ngrok/Tailscale) ou uma URL pública. Um servidor alcançável apenas pelo relay WebSocket não consegue receber pushes do SCIM; o provisionamento JIT continua funcionando nele, este guia não.

Etapas

1. Abra Configurações → Servidor → Início de sessão único → o cartão Provisionamento de utilizadores (SCIM). O cartão mostra o endpoint, por exemplo https://<your-server>/scim/v2/Users.
2. Clique em Gerar token (ou Regenerar token, se já existir um) — o token bearer aparece uma única vez em uma caixa de diálogo e é copiado para a área de transferência. Guarde-o no seu gerenciador de senhas; o servidor mantém apenas uma cópia verificável em tempo constante.
3. Nas configurações de provisionamento do seu IdP, habilite o SCIM com:
   • URL base: o endpoint acima
   • Autenticação: Authorization: Bearer <token>
   • ID do usuário: userName (e-mail) ou externalId — ambos funcionam
4. Teste com um usuário: envie-o a partir do IdP e confirme que ele aparece (a criação via SCIM fixa o externalId do provedor na conta, a mesma fixação que um primeiro login por SSO define).

O que o desprovisionamento faz

Quando o IdP envia active: false (ou DELETE), o SCIM recusa primeiro se a conta for proprietária de um espaço de trabalho (transfira a propriedade antes). Caso contrário:

1. todas as credenciais de dispositivo são revogadas primeiro — as sessões ativas caem em segundos,
2. todas as associações a espaços de trabalho são removidas,
3. a conta é marcada como desativada (ela nunca mais consegue entrar, diga o IdP o que disser depois, até ser explicitamente reativada).

A linha do usuário em si sobrevive — a atribuição em tickets, mensagens e commits é permanente. A reativação (SCIM active: true) restaura o login, mas não as associações: essas precisam de um novo convite ou da política de inclusão automática no momento do login.

Solução de problemas

• 401 em todas as chamadas — o token mudou; regenere-o e atualize o IdP.
• O endpoint não está acessível — o túnel está fora do ar ou o servidor funciona apenas via relay. O SCIM precisa de HTTPS direto; o JIT continua funcionando mesmo assim.
• Erros de push de grupos (501) — intencional: o mapeamento de grupo → papel acontece no login, a partir dos atributos de grupo do SAML/OIDC, e não a partir de grupos enviados por push.