Provisionamento SCIM

O SnapOtter implementa o SCIM 2.0 (System for Cross-domain Identity Management) para o provisionamento automatizado de usuários e grupos. Seu provedor de identidade pode criar, atualizar, desativar e reativar contas de usuário e sincronizar associações a grupos automaticamente.

Recurso enterprise

O provisionamento SCIM requer uma licença enterprise com o recurso scim. Ele não está disponível no plano team. Sem o recurso, todos os endpoints SCIM (exceto discovery) retornam 403.

Pré-requisitos

• Uma instância do SnapOtter em execução, acessível em uma URL pública
• Uma chave de licença enterprise com o recurso scim
• Acesso de administrador ao SnapOtter (a permissão users:manage é necessária para gerar ou revogar um token SCIM)
• Acesso de administrador às configurações de provisionamento do seu provedor de identidade

Início rápido

1. Gere um token bearer SCIM:

curl -X POST https://photos.example.com/api/v1/enterprise/scim/token \
  -H "Cookie: snapotter-session=YOUR_SESSION" \
  -H "Content-Type: application/json"

A resposta contém o token. Salve-o imediatamente; ele não pode ser recuperado novamente.

{
  "token": "a1b2c3d4e5f6...",
  "message": "Save this token - it cannot be retrieved again"
}

2. No seu provedor de identidade, configure o provisionamento SCIM com:
   • URL base: https://photos.example.com/api/v1/scim/v2
   • Autenticação: token bearer (cole o token da etapa 1)

Autenticação

Os endpoints SCIM usam um token Bearer dedicado, separado das sessões de usuário e das chaves de API.

Gerando um token

POST /api/v1/enterprise/scim/token gera um novo token SCIM. Este endpoint requer uma sessão válida com a permissão users:manage.

O token é retornado em texto simples exatamente uma vez. O SnapOtter armazena apenas um hash scrypt. Se você perder o token, revogue-o e gere um novo.

Apenas um token SCIM fica ativo por vez. Gerar um novo token substitui o anterior.

Revogando um token

DELETE /api/v1/enterprise/scim/token revoga o token SCIM atual. Este endpoint também requer users:manage.

Limite de taxa

Os endpoints SCIM têm limite de taxa de 1000 requisições por minuto por token. Exceder esse limite retorna HTTP 429.

Recursos suportados

Recurso SCIM	Conceito no SnapOtter	Criar	Ler	Atualizar	Excluir
User	Conta de usuário	Sim	Sim	Sim	Exclusão suave
Group	Team	Sim	Sim	Sim	Sim

WARNING

Os Groups do SCIM mapeiam para teams do SnapOtter, não para papéis. O SCIM não pode definir o papel de um usuário. Todos os usuários criados via SCIM recebem o papel user. Para alterar o papel de um usuário, use a interface de administração do SnapOtter.

Operações de usuário

Criar usuário

POST /api/v1/scim/v2/Users

Cria uma nova conta de usuário com authProvider definido como scim e o papel user. O usuário é atribuído ao team Default. Se active for false, o papel é definido como disabled em vez disso.

Atributos obrigatórios: userName. Opcionais: externalId, emails, active (padrão true).

Listar e filtrar usuários

GET /api/v1/scim/v2/Users

Retorna uma lista paginada de usuários. Suporta os parâmetros de consulta startIndex e count (máximo de 200 resultados por página).

A filtragem suporta apenas eq (igual), nestes atributos:

• userName eq "jane"
• externalId eq "ext-12345"

Outros operadores de filtro e atributos retornam HTTP 400.

Obter usuário

GET /api/v1/scim/v2/Users/:id

Retorna um único usuário pelo seu ID de usuário no SnapOtter.

Substituir usuário

PUT /api/v1/scim/v2/Users/:id

Substitui os atributos do usuário. Suporta userName, externalId, emails e active. Alterações de nome de usuário são verificadas quanto a conflitos (409 se o novo nome de usuário já estiver em uso por outro usuário).

Aplicar patch em usuário

PATCH /api/v1/scim/v2/Users/:id

Atualização parcial usando SCIM PatchOp. Operações suportadas:

Operação	Caminhos
replace	active, userName, externalId, emails, emails[type eq "work"].value, name.formatted, displayName
add	Igual a replace
remove	externalId, emails

Os caminhos name.formatted e displayName são aceitos por compatibilidade, mas não têm efeito persistente (o SnapOtter não armazena um nome de exibição separado).

Operações replace sem valor (onde o valor é um objeto sem um path) também são suportadas, com as chaves userName, externalId, emails e active.

Desativar usuário (exclusão suave)

DELETE /api/v1/scim/v2/Users/:id

O SnapOtter não exclui usuários permanentemente via SCIM. Em vez disso, o DELETE realiza uma desativação suave:

1. O papel do usuário é alterado do seu valor atual (por exemplo, editor) para disabled:editor, preservando o papel original.
2. A senha do usuário é apagada.
3. Todas as sessões ativas são revogadas.
4. Todas as chaves de API são revogadas.

O usuário não pode mais fazer login nem usar nenhuma chave de API. Seus dados (arquivos, histórico) são mantidos.

Reativar usuário

Para reativar um usuário previamente desativado, envie uma requisição PUT ou PATCH com active: true. O SnapOtter restaura o papel original de antes da desativação (por exemplo, disabled:editor volta a ser editor). Se o papel original não puder ser determinado, ele recorre a user.

Exemplo: desativar e reativar via PATCH

// Deactivate
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

// Reactivate
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": true }
  ]
}

Operações de grupo

Os Groups do SCIM mapeiam para teams do SnapOtter. Criar um grupo cria um team. A associação a grupos controla a qual team um usuário pertence.

Criar grupo

POST /api/v1/scim/v2/Groups

Obrigatório: displayName. Opcional: members (array de { value: userId }).

Listar e filtrar grupos

GET /api/v1/scim/v2/Groups

A filtragem suporta apenas displayName eq "...". Paginado com startIndex e count (máximo de 200 resultados por página).

Obter grupo

GET /api/v1/scim/v2/Groups/:id

Substituir grupo

PUT /api/v1/scim/v2/Groups/:id

Substitui o nome do grupo e a lista completa de membros. Membros existentes que não estão na nova lista são movidos para o team Default.

Aplicar patch em grupo

PATCH /api/v1/scim/v2/Groups/:id

Suporta estas operações:

Operação	Caminho	Efeito
add	members	Adiciona usuários ao team
remove	members[value eq "userId"]	Move o usuário para o team Default
replace	displayName	Renomeia o team
replace	members	Substitui todos os membros (membros removidos são movidos para o team Default)

Excluir grupo

DELETE /api/v1/scim/v2/Groups/:id

Exclui o team. Todos os membros do team excluído são movidos para o team Default. Os usuários não são desativados nem excluídos.

Configuração do IdP

Okta

1. No console de administração do Okta, abra seu aplicativo SnapOtter (ou crie um).
2. Vá para a aba Provisioning e clique em Configure API Integration.
3. Marque Enable API Integration e insira:
   • Base URL: https://photos.example.com/api/v1/scim/v2
   • API Token: o token bearer SCIM gerado acima
4. Clique em Test API Credentials e depois em Save.
5. Em Provisioning > To App, ative:
   • Create Users
   • Update User Attributes
   • Deactivate Users
6. Em Push Groups, configure quais grupos do Okta sincronizar como teams do SnapOtter.

Azure AD / Entra ID

1. No portal do Azure, vá para seu aplicativo enterprise do SnapOtter.
2. Vá para Provisioning e defina Provisioning Mode como Automatic.
3. Em Admin Credentials, insira:
   • Tenant URL: https://photos.example.com/api/v1/scim/v2
   • Secret Token: o token bearer SCIM gerado acima
4. Clique em Test Connection e depois em Save.
5. Em Mappings, configure os mapeamentos de atributos de usuário e grupo. Os padrões geralmente funcionam, mas verifique se userName mapeia para userPrincipalName ou mail conforme desejado.
6. Defina Provisioning Status como On e salve.

O Azure provisiona usuários e grupos em um ciclo de sincronização fixo (normalmente a cada 40 minutos).

Endpoints de discovery

Estes três endpoints estão disponíveis sem autenticação e descrevem as capacidades do servidor SCIM:

Endpoint	Descrição
GET /api/v1/scim/v2/ServiceProviderConfig	Capacidades do servidor e recursos suportados
GET /api/v1/scim/v2/Schemas	Definições de schema de User e Group
GET /api/v1/scim/v2/ResourceTypes	Tipos de recurso disponíveis (User, Group)

O ServiceProviderConfig anuncia estas capacidades:

Recurso	Suportado
Patch	Sim
Bulk	Não
Filter	Sim (máx. 200 resultados, apenas o operador eq)
Change password	Não
Sort	Não
ETag	Não

Limitações

• Filtragem: Apenas o operador eq é suportado. Filtros complexos, os operadores and/or, co (contém) e sw (começa com) não são implementados.
• Operações em lote: Não suportadas.
• Sort e ETag: Não suportados.
• Papéis: O SCIM não pode atribuir papéis do SnapOtter. Todos os usuários provisionados recebem o papel user.
• MAX_USERS: O limite da variável de ambiente MAX_USERS não é aplicado na criação de usuários via SCIM. Se você precisar limitar a contagem de usuários, gerencie as atribuições no seu IdP.
• Um token: Apenas um token SCIM pode ficar ativo por vez. Se vários IdPs precisarem de acesso SCIM, eles precisam compartilhar o token.
• Grupos são teams: Os Groups do SCIM correspondem a teams, não a papéis ou grupos de permissão.

Solução de problemas

403 "SCIM provisioning requires an enterprise license with the scim feature"

Sua licença não inclui o recurso scim, ou nenhuma licença está configurada. O SCIM requer uma licença de plano enterprise. Verifique se SNAPOTTER_LICENSE_KEY está definido e se a licença inclui o recurso scim.

401 "Bearer token required"

A requisição SCIM não incluiu um cabeçalho Authorization: Bearer <token>. Verifique a configuração de provisionamento do seu IdP.

401 "Invalid token"

O token não corresponde ao hash armazenado. Isso acontece se o token foi revogado e regerado. Atualize o token nas configurações de provisionamento do seu IdP.

401 "SCIM not configured"

Nenhum token SCIM foi gerado ainda. Use o endpoint POST /api/v1/enterprise/scim/token para criar um.

409 "User already exists" / "userName already taken"

Já existe um usuário com o mesmo nome de usuário. Isso pode acontecer quando um IdP tenta novamente uma criação que falhou. Verifique se há nomes de usuário duplicados no painel de administração do SnapOtter.

429 "SCIM rate limit exceeded"

O IdP está enviando mais de 1000 requisições por minuto. Isso normalmente acontece durante uma grande sincronização inicial. A maioria dos IdPs tenta novamente automaticamente após a redefinição da janela de limite de taxa. Se o problema persistir, verifique o intervalo de sincronização de provisionamento do seu IdP.

Usuários desprovisionados, mas não removidos da interface

O DELETE do SCIM é uma desativação suave. Usuários desativados ainda aparecem na lista de usuários do administrador com um status desabilitado. Isso é intencional, para que seus dados sejam preservados. O papel deles aparece como disabled:<original-role>.