SCIM 2.0 (provisionamento por IdP)
Implementação de SCIM 2.0 (RFC 7643/7644) para o Microsoft Entra ID e o Okta criarem, actualizarem e desactivarem utilizadores e grupos. Os endpoints vivem em /api/scim/v2 (fora de /api/v1):
Base URL: https://www.etershield.com/api/scim/v2 (o URL do tenant aparece em Definições → SSO, junto ao botão «Gerar token SCIM»).
Autenticação
Authorization: Bearer <token_scim>, apenas este cabeçalho (o SCIM não aceita x-api-key). O token é uma chave nomeada (hash SHA-256, validade de 365 dias, revogável na lista de chaves API) com o scope explícito /api/scim/v2. É gerado por um ADMIN em Definições → SSO e é mostrado uma única vez.
- A chave única do tenant e as chaves nomeadas sem scopes (acesso total) são recusadas no SCIM: criar e desativar contas é demasiado poder para uma chave pensada para, por exemplo, enviar alertas do Wazuh.
- O inverso também vale: o token SCIM, por ter o scope
/api/scim/v2, é recusado em qualquer outra rota (/api/v1/*). - Token em falta, desconhecido, expirado, revogado, sem o scope SCIM ou de tenant inativo →
401. - Rate limit: 600 pedidos/min por tenant (o Entra faz rajadas no ciclo inicial); excedido →
429comscimType: tooMany.
Endpoints
| Método | Rota | Descrição |
|---|---|---|
| GET | /ServiceProviderConfig |
Capacidades: patch e filter (máx. 100 resultados) suportados; bulk, sort, etag e changePassword não suportados |
| GET | /ResourceTypes · /Schemas |
Descoberta dos tipos User e Group e dos atributos lidos/devolvidos |
| GET | /Users |
Lista utilizadores (paginação startIndex / count, máx. 100 por página) |
| POST | /Users |
Cria utilizador → 201 |
| GET · PUT · PATCH · DELETE | /Users/{id} |
Ler · substituir · alterar (PatchOp) · desativar (204) |
| GET | /Groups |
Lista grupos |
| POST | /Groups |
Cria grupo (com members opcionais) → 201 |
| GET · PUT · PATCH · DELETE | /Groups/{id} |
Ler · substituir nome e membros · alterar nome/membros · apagar (204) |
As respostas usam Content-Type: application/scim+json. O {id} é o do EterShield (devolvido no POST e na listagem).
Mapeamento
- User = pertença (
Membership) do utilizador a este tenant.userNameeemails[primary]= email;name/displayName= nome;title= cargo;externalId= identificador no IdP;active= estado da pertença;groups= só leitura (departamentos deste tenant). - Group = departamento do tenant (
TenantDepartment);displayName= nome;members= utilizadores do tenant.
Filtros
Só eq (é o que o Entra e o Okta enviam para encontrar um recurso antes de o criar); o nome do atributo não distingue maiúsculas de minúsculas, e a comparação de email e de nome de grupo também não.
| Recurso | Atributos filtráveis | Exemplo |
|---|---|---|
| Users | userName, externalId |
GET /Users?filter=userName eq "ana@empresa.pt" |
| Groups | displayName, externalId |
GET /Groups?filter=displayName eq "Direcção" |
Qualquer outro filtro (co, sw, and, or, outros atributos…) responde 400 com scimType: invalidFilter.
Comportamento
- Criar utilizador (
POST /Users): exigeuserName(ou email principal) válido. Se o SSO do tenant tiveremailDomains, o domínio do email tem de estar na lista. O papel inicial é odefaultJitRoledo SSO (por omissãoUSER). Respeita o limite de utilizadores do plano (403se atingido). Comactive: falsecria a pertença já inativa. DELETE /Users/{id}desativa, não apaga: a conta e o histórico ficam, e a anonimização RGPD é uma operação à parte. O mesmo efeito temPATCH/PUTcomactive: false;active: truereativa. O último administrador do tenant nunca é desativado (400,scimType: mutability).- PATCH de Users (
replace/add, com ou sempath):active(aceita também"True"/"False"em texto, como o Entra envia),userName,displayName,name.*,title,externalIdeemails[…].value. Operaçõesremovesobre atributos opcionais são ignoradas. - PATCH de Groups:
displayName,externalIdememberscomadd,remove(incluindomembers[value eq "id"]) ereplace. Os membros têm de ser utilizadores do tenant (400caso contrário).PUTsubstitui o nome e a lista de membros. - Mapa de grupos → papel: se o SSO do tenant tiver «Papel por grupo» (
groupRoleMap, nome do grupo → papel), o papel dos utilizadores criados por SCIM passa a seguir a pertença a grupos, mesma regra do JIT, com precedência ADMIN > MANAGER > USER > AUDITOR > VIEWER; sem grupo mapeado aplica-se odefaultJitRole. Nunca atribuiSUPER_ADMIN, nunca altera o papel de quem não foi criado por SCIM e nunca retira o último administrador. - Membros externos: um
POST /Userscom o email de uma conta que já existe noutra organização não cria uma conta nova, cria (ou reativa) a pertença dessa conta a este tenant, como membro externo. O nome e o email de um externo pertencem à organização de origem e não são alterados pelo IdP deste cliente (o pedido é aceite e esses campos são ignorados, para não partir a sincronização do IdP). O cargo, oexternalIde o estado são da pertença e actualizam-se normalmente. Desativar um externo retira-lhe só o acesso a este tenant. O tenant pode recusar externos (allowExternalMembers, Definições → Segurança) e a entrada de um externo exige MFA na conta dele. - Auditoria: cada criação, alteração, desativação e mudança de papel fica no audit log como
scim:<nome do token>.
Erros
Formato urn:ietf:params:scim:api:messages:2.0:Error, com status, detail e, quando aplicável, scimType.
| Código | Quando |
|---|---|
400 |
JSON inválido ou PatchOp sem Operations (invalidSyntax); filtro não suportado (invalidFilter); userName / displayName em falta, domínio fora dos domínios do SSO ou membro inexistente no tenant (invalidValue); desativar o último administrador (mutability) |
401 |
Token em falta, inválido, expirado, revogado, sem o scope /api/scim/v2 ou de tenant inativo |
403 |
Limite de utilizadores do plano atingido; tenant que recusa membros externos; conta externa bloqueada na plataforma |
404 |
Utilizador ou grupo inexistente neste tenant |
409 |
userName já existente (ou já membro ativo), externalId duplicado, displayName de grupo duplicado (uniqueness) |
429 |
Rate limit (tooMany) |
500 |
Erro interno (sem detalhe) |
Configuração no IdP
Microsoft Entra ID (Enterprise application → Provisioning → modo Automatic):
| Campo | Valor |
|---|---|
| Tenant URL | https://www.etershield.com/api/scim/v2 |
| Secret Token | o token SCIM gerado em Definições → SSO |
Depois de «Test Connection», os mapeamentos habituais são userPrincipalName → userName, displayName → displayName, jobTitle → title, objectId → externalId e o estado da conta → active. Retirar a atribuição de um utilizador no Entra chega como active: false (ou DELETE) e desativa-o.
Okta (aplicação SCIM 2.0 → Provisioning → Integration): SCIM connector base URL = https://www.etershield.com/api/scim/v2; Unique identifier field for users = userName; Authentication Mode = HTTP Header, com o token SCIM no formato Bearer <token_scim>; ações a ativar: Push New Users, Push Profile Updates e Push Groups.
Depois de configurar o IdP, validar com o SCIM Validator da Microsoft. O token SCIM nunca deve ficar em ficheiros versionados nem em tickets, só no cofre de segredos do IdP.