description:"Configure o provisionamento SCIM 2.0 para sincronizar usuários e grupos do seu provedor de identidade com o SnapOtter. Abrange Okta, Azure AD / Entra ID e integrações personalizadas."
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.
::: tip 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 {#prerequisites}
- 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`
- Uma conta SnapOtter `admin` integrada com seu conjunto completo de permissões efetivas. Uma função personalizada delegada ou uma chave de API de administrador sem qualquer permissão de administrador não pode gerar ou revogar o token SCIM global.
`POST /api/v1/enterprise/scim/token` gera um novo token SCIM. Como o token pode provisionar e alterar usuários em toda a instância, esse endpoint requer a função `admin` integrada com o conjunto completo de permissões de administrador efetivas. Manter `users:manage` em uma função personalizada não é suficiente.
Os tokens SCIM legados e não versionados são rejeitados. Após atualizar para uma versão que emita tokens `so_scim_v2_...`, gere um novo token e atualize seu provedor de identidade antes de retomar o provisionamento.
`DELETE /api/v1/enterprise/scim/token` revoga o token SCIM atual. Ele tem os mesmos requisitos de administração integrados completos da geração de token.
| 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 {#user-operations}
### Criar usuário {#create-user}
`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.
### Listar e filtrar usuários {#list-and-filter-users}
`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-user}
`GET /api/v1/scim/v2/Users/:id`
Retorna um único usuário pelo seu ID de usuário no SnapOtter.
### Substituir usuário {#replace-user}
`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).
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`.
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 {#reactivate-user}
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`.
::: details Exemplo: desativar e reativar via PATCH
- **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 {#discovery-endpoints}
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 |
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 {#limitations}
- **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 {#troubleshooting}
### 403 "SCIM provisioning requires an enterprise license with the scim feature" {#_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`.
O token está malformado, usa o formato não versionado retirado ou não corresponde ao hash armazenado. Gere um token `so_scim_v2_...` atual e atualize o token nas configurações de provisionamento do seu IdP.
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.
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 {#users-deprovisioned-but-not-removed-from-the-ui}
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>`.
