SCIM 2.0 provisioning

A partir da v4.5, o CipherVault implementa SCIM 2.0 (RFC 7644) para provisionamento automático de usuários e grupos a partir de IdPs corporativos (Okta, Azure AD/Entra ID, OneLogin, JumpCloud, Google Workspace).

Benefícios

• Onboarding/offboarding automático — usuário sai do IdP, conta no CV é desativada em segundos
• Sync de grupos — adicionar usuário ao grupo ciphervault-admins no Okta automaticamente o promove no CV
• Sem CSV imports — fonte da verdade fica no IdP, CV consome eventos
• Compliance — atende SOC 2 CC6.2 (provisioning) e LGPD art. 12

Endpoints SCIM 2.0

Endpoint base: https://cv.acme.com.br/scim/v2

Users

GET    /scim/v2/Users                List/filter
POST   /scim/v2/Users                Create
GET    /scim/v2/Users/:id            Read
PUT    /scim/v2/Users/:id            Replace
PATCH  /scim/v2/Users/:id            Partial update
DELETE /scim/v2/Users/:id            Deactivate (soft delete)

Groups

GET    /scim/v2/Groups               List/filter
POST   /scim/v2/Groups               Create
GET    /scim/v2/Groups/:id           Read
PUT    /scim/v2/Groups/:id           Replace
PATCH  /scim/v2/Groups/:id           Partial update
DELETE /scim/v2/Groups/:id           Delete

Service Provider Configuration

GET    /scim/v2/ServiceProviderConfig
GET    /scim/v2/ResourceTypes
GET    /scim/v2/Schemas

Autenticação

Token bearer dedicado SCIM (separado do JWT de admin):

# Admin gera SCIM token
curl -X POST https://cv.acme.com.br/scim/tokens \
  -H "Authorization: Bearer $CV_TOKEN" \
  -d '{ "name": "okta-scim", "description": "Okta tenant ACME" }'
# → { "token": "cv_scim_..." }

Token é configurado no IdP. Permissões: SCIM-only (não pode criar vaults, mexer em policies, etc.).

Setup — Okta

1. Admin Okta → Applications → "CipherVault" → Provisioning
2. Enable API Integration
3. Configurar:
   • Base URL: https://cv.acme.com.br/scim/v2
   • API Token: cv_scim_...
4. Test API credentials — deve retornar verde
5. Habilitar features:
   • ✅ Create Users
   • ✅ Update User Attributes
   • ✅ Deactivate Users
   • ✅ Sync Password — NÃO (CV usa OAuth/SAML, não password sync)
   • ✅ Group Push

Setup — Azure AD / Entra ID

1. Enterprise Applications → CipherVault → Provisioning
2. Provisioning Mode: Automatic
3. Admin Credentials:
   • Tenant URL: https://cv.acme.com.br/scim/v2
   • Secret Token: cv_scim_...
4. Test Connection → 200 OK
5. Mappings:
   • User: padrão SCIM 2.0 (Microsoft fornece template OOB)
   • Group: padrão SCIM 2.0
6. Save → Start Provisioning

Provisionamento inicial pode levar de minutos a horas para 1000+ users. Modo incremental depois disso roda a cada 40 minutos (configurável no Azure).

Filtros SCIM suportados

GET /scim/v2/Users?filter=userName eq "alice@acme.com.br"
GET /scim/v2/Users?filter=active eq true and emails.value sw "@acme.com.br"
GET /scim/v2/Groups?filter=displayName eq "ciphervault-admins"

Operadores: eq, ne, co (contains), sw (starts with), ew (ends with), gt, ge, lt, le, and, or, not.

Mapeamento IdP → CV

SCIM attribute	CV field
userName	users.email
name.givenName + name.familyName	users.name
active	users.active
emails[primary=true].value	users.email (validado)
groups[]	vault_members + iam_groups (via mapping)
externalId	users.external_id
enterprise.department	users.department
enterprise.manager	users.manager_email

Group → CipherVault IAM

Grupos do IdP com prefixo configurável (default ciphervault-) são mapeados para IAM groups do CV:

IdP group	CV IAM group
ciphervault-admins	Administradores
ciphervault-devops	DevOps
ciphervault-security	Security
ciphervault-readers	Somente Leitura
outros	(ignorados ou mapeados via iam_group_mappings)

Configure mappings customizados:

curl -X PUT https://cv.acme.com.br/scim/iam-group-mappings \
  -d '{
    "mappings": {
      "billing-eng": "billing-vault-contributors",
      "fraud-team-prd": "fraud-vault-owners"
    }
  }'

Deactivation

DELETE /scim/v2/Users/:id ou PUT com active: false:

• User vira active=false no CV
• Sessions ativas invalidadas em < 60s
• AppConnections do user NÃO revogadas (devs podem ter compartilhado)
• PATs do user revogados imediatamente
• Audit log severity=high: user_deactivated_via_scim

Reativação: PUT active: true → user reativado, mas precisa de novo login.

Observability

cv_scim_requests_total{endpoint, method, result}
cv_scim_users_provisioned_total{action}        # action: create, update, deactivate
cv_scim_groups_synced_total
cv_scim_errors_total{type}

Boas práticas

• Token SCIM rotacionado a cada 6 meses — POST /scim/tokens/:id/rotate
• Não dual-source — defina um IdP como source of truth. Múltiplos podem causar conflitos
• Group push, não user push apenas — grupos são chave para autorização no CV
• externalId sempre populado — facilita reconciliação se IdP mudar
• Audit alertas em user_deactivated_via_scim fora do horário comercial — pode indicar incidente no IdP
• DR scenario — se IdP cai, mantenha pelo menos 1 admin local (source: "local") com MFA — emergency break-glass