Noções básicas de provisionamento SCIM para manter usuários sincronizados com seu provedor de identidade: fluxos de criar, atualizar e desativar, campos requeridos e passos de testes seguros.
SCIM provisioning resolve um problema simples e doloroso: a lista de pessoas que podem acessar um app aos poucos deixa de corresponder à lista no seu provedor de identidade (IdP). Alguém é contratado, muda de nome, troca de equipe ou sai, e o app nem sempre reflete essa mudança imediatamente.
Provisioning significa que o IdP empurra as mudanças de usuário para o app automaticamente. Em vez de um administrador convidar usuários, atualizar perfis e remover acessos manualmente, as mudanças começam no IdP e o app acompanha.
Quando convites e offboarding são manuais, as mesmas falhas aparecem repetidamente. Novas contratações esperam por acesso porque alguém esqueceu de enviar um convite. Ex-funcionários mantêm acesso porque o offboarding foi perdido. Nomes, e-mails e departamentos divergem entre ferramentas. Auditorias ficam mais difíceis porque você não pode confiar na lista de usuários do app. Chamados de suporte se acumulam (não consegue entrar, acesso errado, ainda vendo dados antigos).
SCIM é uma boa opção quando você precisa de controle confiável do ciclo de vida de usuários em escala, especialmente para ferramentas internas, painéis de administração e portais de clientes onde o acesso deve refletir decisões de RH e TI.
SSO por si só geralmente não basta. SSO responde “Como o usuário faz login?” SCIM responde “Esse usuário deve existir no app, e como deve ser a conta dele agora?”
Comece com uma regra: escolha um sistema único que esteja “certo” sobre quem é o usuário e o que ele pode acessar. Na maioria das empresas, esse sistema é o IdP (Okta, Azure AD, Google Workspace).
O IdP é onde as pessoas são criadas, desabilitadas e atribuídas a grupos. O service provider (SP) é o app que recebe essas decisões e aplica em seu próprio banco de usuários. Isso pode ser um produto SaaS ou um app interno customizado que você construiu.
Uma vez que o IdP é a fonte da verdade, o app não deve discordar dele. Se um administrador desabilita um usuário no IdP, o app deve tratar esse usuário como desabilitado mesmo que alguém tente reativá-lo localmente. O mesmo vale para associação a grupos quando grupos determinam acesso.
Provisioning geralmente é push-based: o IdP envia mudanças ao app quando algo acontece. Isso difere de sincronização pull, onde o app pergunta periodicamente o que mudou. Push é mais rápido e claro, mas erros podem ter efeito imediato, então padrões e regras de correspondência importam.
A maior parte da atividade é impulsionada por eventos normais de RH e TI: novas contratações, mudanças de função, licença e desligamentos. Se você mantiver status e atribuições de grupo controlados no IdP, reduz duplicados, contas “fantasma” e lacunas de acesso de última hora quando alguém muda de equipe.
A maioria das configurações de provisionamento se resume a uma promessa: o IdP diz ao seu app quem existe e se essa pessoa deve conseguir autenticar. Seu app precisa lidar com alguns estados do ciclo de vida de forma consistente.
A maioria das equipes pensa em três estados:
Create geralmente ocorre quando um administrador atribui o app a uma pessoa no IdP, ou quando ela entra em um grupo sincronizado. Seu endpoint SCIM deve armazenar o que você precisa para identificar essa pessoa depois: um ID único estável do IdP (frequentemente o SCIM id), além de um valor de login (comum userName). Se seu app exige email, deixe isso explícito no mapeamento para que a criação não falhe no meio do processo.
Update acontece quando o IdP altera um campo do perfil ou uma atribuição. Aplique mudanças a campos de identidade e comunicação (nome, email, departamento) sem alterar o acesso de forma inesperada. O campo mais sensível é o identificador de login. Se userName puder mudar, você ainda precisa identificar a mesma pessoa usando um identificador imutável. Caso contrário, você criará duplicados.
Deactivate deve bloquear o acesso rapidamente sem perder dados de negócio. O IdP normalmente define active=false. Seu app deve tratar isso como “não pode autenticar, não pode usar API”, preservando registros, histórico de auditoria e referências.
Reactivate é o inverso. active=true deve restaurar o acesso para a mesma conta, não criar uma nova. Se o IdP considera a pessoa a mesma, seu app também deve considerar, mesmo que email ou display name tenham mudado enquanto ela esteve ausente.
Provisioning funciona quando o app e o IdP concordam em duas coisas: como identificar um usuário e quais atributos o IdP pode sobrescrever.
SCIM é flexível, mas a maioria dos apps acaba confiando nos mesmos atributos principais:
id do SCIM, frequentemente pareado com externalId do IdP)userName, frequentemente usado para login)name.givenName e name.familyName, ou displayName)active: true/false)O identificador é o detalhe chave. Email parece único, mas muda. Se você fizer o match de usuários apenas por email e alguém muda de nome (casamento, rebrand, migração de domínio), o IdP pode parecer estar criando uma nova pessoa em vez de atualizar a antiga. Esse é um caminho comum para duplicados.
Escolha uma regra clara: quais campos são controlados pelo IdP (IdP vence sempre) e quais são controlados pelo app (o app pode alterar sem que seja revertido).
Uma divisão comum e segura:
active, email/username, given e family name, display nameSe seu app permite que pessoas editem o nome, decida se essas edições devem persistir ou serem substituídas pela próxima atualização SCIM. Qualquer uma das escolhas funciona — o problema é quando isso é imprevisível.
Espere campos em branco e formatos inconsistentes. Alguns diretórios enviam apenas displayName. Outros enviam given e family name mas sem display name. Um fallback prático é construir displayName a partir de given e family quando necessário, e lidar graciosamente com family names ausentes.
Valide campos críticos. Se userName estiver vazio, ou não for um email quando seu login exige email, rejeite a requisição com um erro claro e registre-o. Criar silenciosamente um usuário que não pode autenticar vira uma falha lenta.
Um “match” é quando o IdP e seu app concordam que dois registros representam a mesma pessoa. A maioria dos problemas de provisionamento se resume a quais campos seu app usa para encontrar um usuário existente quando o IdP envia uma atualização.
Faça o match primeiro em um identificador estável e não-humano. Trate email e username como dados de perfil que podem mudar.
Chaves comuns de emparelhamento (mais confiável para menos confiável):
id (estável por usuário nesse app)Se seu app faz match apenas por email, uma mudança de email pode parecer uma nova pessoa e criar um duplicado. Em vez disso, mantenha o ID externo como chave primária e permita que o email seja atualizado sem alterar a identidade.
Duplicados tendem a aparecer em três situações:
Para reduzir atualizações conflitantes, escolha um proprietário para os campos de perfil principais. Se o IdP possui nomes, email e status ativo, não confie em edições manuais dentro do app para esses campos (ou marque-as claramente como “gerenciadas pelo IdP”).
Se dois usuários do IdP acabarem apontando para um usuário do app, não faça merge automático. Pause o SCIM para essas contas, decida qual identidade do IdP está correta, relacione novamente usando o external ID e desative a errada. Isso mantém o histórico de auditoria consistente.
Quando o SCIM começa a enviar usuários e grupos, o maior risco é acesso surpresa. Mantenha o modelo simples: conceda acesso com base em grupos do IdP, ou com base em funções gerenciadas dentro do app. Misturar ambos sem regra clara leva a incidentes de “por que essa pessoa recebeu acesso?”.
A concessão por grupo funciona bem quando seu IdP já é onde os administradores gerenciam a membresia de equipe. Concessão por função funciona melhor quando donos do app precisam ajustar permissões sem mexer no IdP. Se for preciso combinar, defina qual ganha quando houver conflito.
Seja conservador com padrões. Se dados de grupo estiverem atrasados ou faltando (comum no primeiro sync), crie a conta mas não dê acesso sensível até que o grupo esperado chegue. Trate “sem grupos” como “sem acesso” em vez de chutar.
Um conjunto de regras previsível:
Remoção de grupo e desativação são diferentes. Remoção de grupo deve reduzir acesso mantendo a conta utilizável se o usuário ainda pertencer a outros grupos. Desativação é o corte definitivo para offboarding.
Mantenha a documentação curta, mas específica: quais grupos mapeiam para quais permissões, o que acontece se grupos estiverem faltando, quem é dono das mudanças de grupo (TI vs dono do app) e mais ou menos quanto tempo as mudanças levam para aparecer.
Comece em um ambiente não-produtivo (tenant separado, workspace ou instância de staging) com um diretório limpo e algumas contas de teste. Ative o provisionamento lá primeiro.
Antes de conectar qualquer coisa, crie uma conta de administrador de emergência que não seja gerenciada pelo SCIM. Dê a ela uma senha forte e mantenha-a fora das atribuições SCIM do IdP. Essa é sua forma de voltar se o provisionamento desabilitar seus administradores normais.
Use um grupo piloto pequeno (2–5 pessoas). Inclua um administrador e um usuário comum. Não habilite provisionamento para toda a empresa até que o piloto se comporte exatamente como esperado.
Um plano de testes simples que cobre as partes arriscadas:
Não confie apenas na interface. Verifique os logs SCIM em ambos os lados e confirme timestamps: quando o IdP enviou a mudança, quando o app processou e quais campos foram alterados.
Se qualquer passo criar uma segunda conta, desativar o usuário errado ou derrubar acesso administrativo, pare o rollout e corrija o matching e o mapeamento de atributos antes de ampliar além do piloto.
A maioria dos problemas não é “bug de SCIM”. Vem de pequenas suposições que parecem inofensivas na configuração e depois quebram em escala. Regras de matching e padrões importam mais que o conector.
Padrões comuns que levam a contas desabilitadas, duplicados e expansão de acessos:
Um modo de falha real: durante uma mudança de domínio, TI renomeia emails. Se o app faz match por email, o SCIM não encontra a conta existente, cria uma nova e depois desativa a antiga. O usuário fica com dois perfis, histórico quebrado e sem acesso no pior momento.
Faça match em um identificador único estável (geralmente o ID imutável do IdP) e trate email como algo mutável.
Decida quem pode editar campos de usuário no app. Se o SCIM é a fonte da verdade, ou bloqueie edições manuais para campos gerenciados pelo IdP, ou deixe claro que serão revertidas.
Comece com um piloto pequeno e padrões de menor privilégio. É mais fácil adicionar acesso quando você confia no fluxo do que limpar depois de super-provisionar ou executar uma desativação ruim.
Antes de expandir além do piloto, verifique o ciclo de vida completo: criar a conta certa, atualizar a mesma conta depois e remover acesso quando necessário.
Use uma identidade de teste fresca no IdP (não um funcionário real). Provisione-a e confirme que a conta aparece com o username, email, display name e status esperados no app.
Depois execute um teste de mudança. Atualize o nome e o email da pessoa no IdP e observe o que acontece no app. Você quer que um registro de usuário seja atualizado, não que um segundo usuário seja criado.
Por fim, teste remoção e recuperação. Desative o usuário no IdP e confirme que ele não consegue entrar e não tem mais acesso. Então reative-o e confirme que o acesso volta de forma previsível (funções corretas, grupos corretos, sem direitos administrativos acidentais).
Um checklist curto de go-live:
Imagine uma empresa de 200 pessoas que usa um IdP e SCIM para gerenciar acesso a uma ferramenta interna.
Na segunda, Maya entra no Sales Ops. Quando TI atribui o app a Maya no IdP, o SCIM envia um Create. Um novo usuário aparece no app com o identificador único certo, email e um valor de departamento “Sales Ops”. Se grupos dirigem acesso, o app também recebe a associação a grupo que concede a função correta.
Na quinta, Maya passa para RevOps. Isso dispara um Update. Maya continua a mesma pessoa (mesmo external ID), mas os atributos mudam. Se permissões dependem de departamento ou grupos, é aqui que erros aparecem, então verifique imediatamente.
No fim do mês, Maya sai. O IdP desabilita a conta ou remove a atribuição ao app, e o SCIM envia um Deactivate (frequentemente uma atualização como active=false). Maya não consegue mais entrar, mas seus dados históricos continuam pertencendo ao negócio.
Um administrador pode verificar rapidamente:
Se um contratado precisa de acesso temporário, não reutilize a conta da Maya. Crie uma identidade separada de contratante no IdP, coloque-a em um grupo com tempo limitado e deixe o provisionamento cuidar da remoção.
Provisionamento pode ser fácil de fazer funcionar e ainda assim difícil de operar bem a longo prazo. Trate-o como um pequeno sistema com regras, donos e um registro de mudanças.
Anote seu mapeamento de atributos e regras de acesso em um só lugar: quais campos do IdP populam username, email, nome, departamento, manager e quais grupos concedem acesso. Quando alguém perguntar por que uma pessoa foi desabilitada, você quer uma resposta única, não cinco suposições.
Escolha um piloto que seja grande o suficiente para ser real, mas pequeno o bastante para desfazer. Defina checkpoints (dia 1, semana 1, semana 2), torne passos de rollback explícitos (pausar atribuições, parar SCIM, restaurar acesso) e mantenha a conta de administrador de emergência fora do SCIM.
Monitoramento evita que você descubra problemas por usuários irritados. Concorde sobre o que será monitorado e quem será notificado: picos em desativações ou reativações, crescimento súbito de duplicados, volume de updates incomum (muitas vezes um loop de mapeamento) e usuários criados sem atributos obrigatórios.
Se você está construindo o app internamente, planeje o gerenciamento de usuários cedo: criar usuários, atualizar perfis, desativar contas e atribuir funções. É muito mais fácil quando essas são funcionalidades de primeira classe.
Se você está prototipando ferramentas internas, AppMaster (appmaster.io) pode ser uma maneira prática de construir backend, web app e app móvel em um só lugar, e então conectar SCIM pelas suas APIs quando seu modelo de usuário e regras de acesso estiverem estáveis.
What does SCIM provisioning actually do?SCIM provisioning mantém automaticamente a lista de usuários do seu app alinhada com seu provedor de identidade (IdP). Quando alguém é contratado, tem o nome alterado, muda de equipe ou é desligado, o IdP envia essas mudanças para o app para que os administradores não precisem convidar, editar ou remover usuários manualmente.
How is SCIM different from SSO?SSO controla apenas como o usuário se autentica. SCIM controla se o usuário deve existir no app, se está ativo ou inativo e como seus campos de perfil devem aparecer agora. Usar os dois juntos evita situações como “ele consegue entrar, mas não deveria ter conta” e “ele tem conta, mas não tem acesso”.
Who should be the source of truth: the IdP or the app?Trate o IdP como a fonte da verdade para campos de identidade e status do ciclo de vida, e faça o app segui-lo de forma consistente. Se o app permite edições locais, defina claramente quais campos o IdP pode sobrescrever para evitar idas e vindas confusas.
What user lifecycle states should my app support for SCIM?A maioria das equipes usa três estados: ativo, inativo (desativado) e excluído. Na prática, muitos apps evitam exclusões permanentes e usam desativação, porque ela bloqueia o acesso mantendo os dados do negócio e o histórico de auditoria intactos.
Which fields are the minimum needed to support SCIM safely?Armazene um identificador único estável vindo do IdP (geralmente o id do usuário SCIM, às vezes acompanhado de um ID imutável do IdP), além de um valor de login como userName e quaisquer campos de comunicação exigidos, como email. O identificador estável evita duplicados quando emails ou nomes de usuário mudam depois.
Should I match users by email or by an external ID?Combine usuários primeiro por um identificador imutável, não por email. Email e nomes de usuário mudam em renomes, migrações de domínio e rebrandings; usá-los como chave primária é uma das formas mais rápidas de criar contas duplicadas.
How do I avoid SCIM updates overwriting the wrong things?Defina quais atributos o IdP possui (normalmente status active, email/username e campos de nome) e aplique essas atualizações automaticamente. Mantenha campos específicos do app (como preferências ou notas internas) sob controle do app para que updates SCIM não apaguem dados locais inesperadamente.
What’s the safest way to test SCIM without locking people out?Comece com um piloto pequeno em um ambiente não-produtivo e mantenha uma conta de administrador de emergência (‘break-glass’) fora do SCIM para recuperar o acesso caso algo dê errado. Teste criar, atualizar (especialmente mudanças de email), desativar e reativar, e confirme que você sempre atualiza o mesmo registro de usuário em vez de criar um segundo.
Why do duplicates happen, and how do I fix them?Os motivos mais comuns são: fazer matching apenas por email, faltar atributos necessários durante a criação ou provisionar a mesma pessoa de dois lugares (convites manuais + SCIM, ou múltiplos IdPs). A correção geralmente envolve escolher um ID autoritativo, pausar o provisionamento para as contas afetadas e re-ligar identidades em vez de mesclar automaticamente os registros.
How should groups and roles work with SCIM so access stays predictable?Adote o princípio do menor privilégio: crie a conta com acesso mínimo ou nenhum acesso, então conceda permissões somente quando o grupo ou função esperada chegar. Se os dados de grupo estiverem faltando ou atrasados, trate isso como “sem acesso” em vez de chutar, e faça da desativação uma sobreposição que revogue o acesso independentemente da associação a grupos.
21 de jan. de 2026
8 min
20 de jan. de 20268 min
20 de jan. de 20268 minExperimente o AppMaster com plano gratuito.
Quando estiver pronto, você poderá escolher a assinatura adequada.
