Como configurar o SCIM 2.0? – netLex | Central de Ajuda

🎯 Objetivo

Neste artigo, você vai aprender o que é o SCIM 2.0, quais são os pré-requisitos para ativá-lo, como gerar o token de autenticação pelo painel e como configurar o seu Identity Provider (IdP) para provisionar e desprovisionar usuários no netLex de forma automática.

Este artigo contém as seções:

O que é o SCIM?
Pré-requisitos
Como configurar pelo Painel (Admin)
Como configurar no Identity Provider
Endpoints disponíveis
Fluxo de provisionamento de usuário
Schema do usuário SCIM
Desprovisionamento
Considerações de segurança
Dúvidas frequentes

💡 O que é o SCIM?

O SCIM 2.0 (System for Cross-domain Identity Management — RFC 7643/7644) é um protocolo padrão para provisionamento automatizado de usuários. Ele permite que um Identity Provider (IdP) — como Okta, Azure AD/Entra ID ou OneLogin — crie, atualize e desative usuários no netLex automaticamente, sem nenhuma intervenção manual.

Em outras palavras: quando um colaborador entra ou sai da empresa, o SCIM garante que o acesso ao netLex seja ativado ou revogado de forma automática e segura, direto pelo seu sistema de identidade.

⚠️ Pré-requisitos

Antes de configurar o SCIM, certifique-se de que o SSO via SAML já está ativo na sua empresa. O SCIM só pode ser habilitado após essa etapa — tentar gerar um token sem o SAML configurado retornará o erro de validação SAML_NOT_CONFIGURED.

🛠️ Como configurar pelo Painel (Admin)

Passo 1 — Acessar a seção SCIM

Navegue até Configurações → Single Sign-On → SCIM no painel administrativo.

Passo 2 — Gerar o token

Clique em "Gerar Novo Token". O sistema irá:

Revogar automaticamente qualquer token anterior (apenas um token ativo é permitido por empresa);
Criar um novo token com o prefixo sk-;
Exibir o token em texto puro apenas uma vez — copie imediatamente!

⚠️ Atenção: o token não é recuperável após fechar a tela. Se perdido, será necessário gerar um novo (o anterior é revogado automaticamente).

Após a geração, a tabela exibirá as seguintes informações:

Campo	Descrição
Status	Sempre `Ativo` enquanto existir
Token	Texto completo só na criação; depois mostra apenas os últimos 4 caracteres
Criado por	Nome do usuário que gerou o token
Criado em	Data de criação
Último uso	Última vez que o IdP autenticou com o token

Passo 3 — Revogar o token (quando necessário)

Clique no ícone de lixeira na tabela. O token é soft-deleted (auditável) e um novo pode ser gerado a qualquer momento.

⚙️ Como configurar no Identity Provider

Com o token em mãos, configure o seu IdP com os seguintes dados:

Parâmetro	Valor
SCIM Base URL	`https://<dominio>/api/scim/v2`
Autenticação	Bearer Token (RFC 6750)
Token	O valor gerado no painel
Versão SCIM	2.0

Todas as requisições às rotas de usuário devem incluir o seguinte header de autenticação:

Authorization: Bearer sk-<seu_token>

🔌 Endpoints disponíveis

A API SCIM do netLex disponibiliza dois grupos de endpoints:

Discovery (sem autenticação)

Método	URL	Descrição
`GET`	`/api/scim/v2/ServiceProviderConfig`	Capacidades do servidor
`GET`	`/api/scim/v2/ResourceTypes`	Tipos de recursos suportados
`GET`	`/api/scim/v2/ResourceTypes/{id}`	Tipo de recurso específico
`GET`	`/api/scim/v2/Schemas`	Schemas disponíveis
`GET`	`/api/scim/v2/Schemas/{schemaId}`	Schema específico

Usuários (requer Bearer Token)

Método	URL	Descrição
`GET`	`/api/scim/v2/Users`	Listar usuários (com filtro e paginação)
`GET`	`/api/scim/v2/Users/{id}`	Buscar usuário por ID
`POST`	`/api/scim/v2/Users`	Provisionar (criar) usuário
`PUT`	`/api/scim/v2/Users/{id}`	Substituir dados do usuário
`PATCH`	`/api/scim/v2/Users/{id}`	Atualizar campos do usuário
`DELETE`	`/api/scim/v2/Users/{id}`	Desprovisionar (revogar acesso)

💡 Rate limits: Discovery → 60 req/min; Usuários → 120 req/min.

🔄 Fluxo de provisionamento de usuário

Ao receber um POST /Users, o sistema executa a seguinte lógica para evitar duplicidades:

Recebe userName (e-mail) e externalId;
Busca o usuário pelo externalId;
Se não encontrado, busca pelo userName (e-mail):
- Não existe → cria novo usuário (isSso=true);
- Existe, mas deletado → restaura e vincula o externalId;
- Existe e ativo → associa o externalId se ainda não tiver.

⚠️ Regra de conflito: se o usuário já possui um scim_external_id diferente do recebido, a operação é rejeitada com o erro USER_ALREADY_ASSOCIATED_WITH_DIFFERENT_EXTERNAL_IDENTITY.

📋 Schema do usuário SCIM

Os campos suportados no payload de usuário são:

Campo SCIM	Descrição	Obrigatório
`userName`	E-mail do usuário	Sim
`externalId`	ID do usuário no IdP	Não
`name.formatted`	Nome completo	Não
`name.givenName`	Primeiro nome	Não
`name.familyName`	Sobrenome	Não
`active`	`true` = ativo / `false` = desativa e revoga tokens	Não
`emails[].value`	E-mail (alternativo ao userName)	Não

Exemplo de payload de criação:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "joao.silva@empresa.com",
  "externalId": "idp-user-123",
  "name": {
    "formatted": "João Silva",
    "givenName": "João",
    "familyName": "Silva"
  },
  "active": true
}

A listagem de usuários também suporta filtro por userName (GET /Users?filter=userName eq "email@empresa.com") e paginação (?startIndex=1&count=50, máximo de 200 por página).

🚫 Desprovisionamento

O desprovisionamento não exclui o usuário. O usuário é desativado e permanece na base de dados do netLex com todo o seu histórico preservado. Os tokens de acesso são revogados durante o processo, mas o bloqueio de um novo login deve ser garantido pela configuração SAML.

Existem duas formas de desprovisionar um usuário:

Via DELETE: DELETE /api/scim/v2/Users/{id} — desativa o usuário e revoga automaticamente todos os tokens de aplicação e OAuth vinculados a ele.
Via PATCH: enviar PATCH com active: false produz o mesmo efeito: desativa o acesso e revoga os tokens, sem remover o usuário.

Um usuário desprovisionado pode ser reprovisionado a qualquer momento via POST /Users.

🔒 Considerações de segurança

Tokens são armazenados como hash SHA-256 — o texto puro nunca fica salvo no servidor;
O valor do token é exibido apenas no momento da criação;
Cada empresa tem no máximo um token ativo;
Gerar um novo token revoga o anterior automaticamente;
Toda autenticação SCIM registra last_used_at para fins de auditoria.

❓ Dúvidas frequentes

Preciso de SAML para usar o SCIM?
Sim. O SCIM só pode ser configurado após o SSO via SAML estar ativo na empresa. Tentar gerar um token sem o SAML ativo retornará o erro SAML_NOT_CONFIGURED.

O que acontece se eu perder o token do SCIM?
Não é possível recuperá-lo. Será necessário gerar um novo token — o anterior é revogado automaticamente na geração do novo.

Posso ter mais de um token ativo ao mesmo tempo no SCIM?
Não. O netLex permite apenas um token SCIM ativo por empresa. Gerar um novo revoga o anterior.

O desprovisionamento exclui o usuário da plataforma?
Não. O usuário é desativado e seu histórico é preservado. Os tokens de acesso são revogados, mas o registro permanece na base de dados do netLex.

É possível restaurar um usuário desprovisionado?
Sim! Basta enviar um novo POST /Users com os dados do usuário. O sistema identificará o registro existente e o restaurará automaticamente.

Quais IdPs são compatíveis com o SCIM do netLex?
Qualquer IdP que suporte SCIM 2.0 com autenticação Bearer Token é compatível, incluindo Okta, Azure AD/Entra ID e OneLogin.