- O que é
- Endpoints SCIM
- Configurar (passo a passo)
- Autenticação
- O que é sincronizado
- Auditoria
- Solução de problemas
- Relacionado
O que é
A qlture implementa um servidor SCIM 2.0: nós somos o Service Provider e o seu provedor de identidade (IdP) é o cliente. Com isso, criar, atualizar e desativar usuários (e grupos) na qlture acontece automaticamente, dirigido pelo seu diretório. Chega de convidar pessoa por pessoa e de esquecer de remover quem saiu.
Compatível com Microsoft Entra ID, Google Workspace e Okta.
flowchart LR
I["Seu IdP<br/>Entra · Google · Okta"] -->|SCIM 2.0| Q{Ação}
Q -->|Criar / atualizar| U[Usuário na qlture]
Q -->|active = false| D[Desativa + encerra sessões]
Q -->|Grupos| G[Grupos sincronizados]
classDef hl fill:#c6ff00,stroke:#c6ff00,color:#070a0e;
class U hl
Endpoints SCIM
O IdP conversa com a Base URL que o painel exibe no campo URL do tenant (SCIM) — copie-a com o botão Copiar. Abaixo dela ficam os recursos padrão do protocolo: /Users, /Groups, /ServiceProviderConfig, /ResourceTypes e /Schemas.
Configurar (passo a passo)
No painel, em Configurações → Provisionamento (acesso TENANT_ADMIN):
- Clique em Gerar token. A qlture cria um bearer token no formato
scim_<...>. - Copie o token agora — ele aparece uma única vez. Guardamos apenas um hash (SHA-256); não é possível recuperá-lo depois.
- No seu IdP, cadastre a aplicação de provisionamento com:
- Tenant URL / Base URL: a URL exibida no painel (botão Copiar).
- Secret Token: o token
scim_...que você copiou.
- Defina o papel padrão dos usuários provisionados (o padrão é
COLLABORATOR). - Ative o provisionamento no IdP e rode uma sincronização de teste.
O token é mostrado só na geração. Se você perder, rotacione — gere um novo e atualize o IdP. Rotacionar invalida o token anterior imediatamente.
Autenticação
Cada tenant tem seu próprio bearer token. Guardamos apenas o SHA-256 dele; o token em claro aparece uma vez, na geração. A cada requisição do IdP, resolvemos o tenant pelo hash e atualizamos o horário da última sincronização, que você vê no painel.
O que é sincronizado
O mapeamento entre os atributos SCIM e o modelo da qlture:
| Atributo SCIM | Campo na qlture |
|---|---|
userName / emails |
e-mail (chave) |
name.givenName + familyName / formatted / displayName |
nome |
active |
status (false → desativa e encerra as sessões) |
extensão enterprise → department |
departamento |
title |
cargo |
externalId |
referência externa do usuário |
| Groups | coleção de grupos da qlture |
Pontos importantes:
- Usuários provisionados entram como
COLLABORATORpor padrão (configurável), sem senha. Eles autenticam por OTP no agente ou por SSO. - Definir
active: falseno IdP desativa o usuário na qlture e mata as sessões ativas no mesmo instante (soft delete — o histórico é preservado). - O provisionamento respeita o limite de usuários do seu plano.
- Grupos do IdP viram grupos na qlture, prontos para segmentar campanhas.
O PATCH cobre as duas formas que os IdPs usam para o active (com e sem path) e é case-insensitive, então Entra, Google e Okta funcionam sem ajuste.
Auditoria
Todas as operações de provisionamento entram no log de auditoria do tenant: scim.user.provision, scim.user.update, scim.user.deprovision e scim.token.rotate. Você tem rastreabilidade completa de quem foi criado, alterado ou desligado — e quando.
Solução de problemas
O IdP recebe erro de “empty request” ou 400 ao criar usuários.
Os IdPs enviam Content-Type: application/scim+json. A qlture já trata isso corretamente — se você estiver rodando um ambiente próprio, garanta que esse content-type seja aceito antes do parser de JSON.
A sincronização “funciona” mas não aparece ninguém. Confira o papel padrão e o limite de usuários do plano. Usuários acima do limite não são criados.
Preciso trocar o token. Use Rotacionar no painel. O token antigo para de funcionar na hora; atualize o segredo no IdP.
Relacionado
- SSO — autenticação dos gestores. Combine SSO (login) + SCIM (ciclo de vida).
- Primeiros passos — papéis e provisionamento.
