--- title: "Usando a API SCIM da Cato para Aplicativos SCIM Personalizados" slug: "using-the-cato-scim-api-for-custom-scim-apps" updated: 2026-07-30T01:56:03Z published: 2026-07-30T01:56:03Z canonical: "knowledge.catonetworks.com/using-the-cato-scim-api-for-custom-scim-apps" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.catonetworks.com/llms.txt > Use this file to discover all available pages before exploring further. # Usando a API SCIM da Cato para Aplicativos SCIM Personalizados Este artigo descreve como usar a API SCIM da Cato para provisionamento de usuários e grupos de usuários com um provedor de identidade (IdP). Para mais informações sobre aplicativos SCIM personalizados no locatário do IdP, veja [Criando um Aplicativo SCIM Personalizado para um IdP](/v1/docs/creating-a-custom-scim-app-for-an-idp). ## Aplicativo SCIM Personalizado Cato Para usar um aplicativo SCIM personalizado para provisionar usuários e grupos de usuários em sua conta Cato, crie o aplicativo no Aplicativo de Gerenciamento Cato (CMA). Além disso, é necessário mapear os atributos SCIM da Cato para os atributos do seu IdP. ### Criar um Aplicativo SCIM Personalizado no CMA Para usar a API SCIM, você deve primeiro criar um aplicativo SCIM personalizado no CMA. Este aplicativo permite integrar seu provedor de identidade (IdP) à plataforma Cato. **Para criar um aplicativo SCIM personalizado no CMA:** 1. No menu de navegação, selecione **Acesso > Serviços de Diretório**. 2. Na guia SCIM, clique em **Novo.** 3. Digite um nome para o aplicativo. 4. Em **Provedor**, selecione **Personalizado**. 5. Clique em **Gerar Token** e copie o valor; ele não estará disponível depois que você salvar e será necessário criar um novo token. 6. Clique em **Salvar**. 7. Ao chamar os endpoints da API SCIM descritos abaixo, você precisará dos seguintes valores para autenticação: - **URL Base SCIM:** Usado como caminho base para solicitações de API - **Token de Portador:** Usado para autenticar solicitações de API ### Atributos SCIM da Cato Esses são os atributos SCIM para usuários e grupos de usuários da Cato que você precisa mapear para os atributos correspondentes do IdP. | Atributo de Usuário da Cato | Description | | --- | --- | | nomeDeUsuario | Nome de usuário para autenticação | | user.firstName | Nome do usuário | | user.lastName | Sobrenome do usuário | | user.email | Endereço de email | | user.displayName | Nome de exibição do usuário | | phoneNumbers[type eq "work"].value | Número de telefone comercial do usuário (incluindo prefixo) | | externalId | ID do usuário (utilizado em eventos) | | Atributo de Grupo de Usuários da Cato | Description | | --- | --- | | active | O usuário está atribuído e ativo no aplicativo SCIM | | displayName | Nome do grupo de usuários | | members | Usuários que pertencem ao grupo de usuários | | externalId | ID do grupo de usuários (usado em eventos) | ## Compreendendo a API SCIM da Cato ### Autenticando na API SCIM da Cato Os clientes autenticam-se na API SCIM usando autenticação de token de portador, conforme definido pela RFC 6750. Todas as solicitações de API devem incluir os seguintes cabeçalhos HTTP: ```plaintext Authorization: Bearer Content-Type: application/json ``` Você pode obter o token de acesso no Aplicativo de Gerenciamento Cato. ### Caminho Base para Endpoints SCIM Todos os endpoints da API SCIM usam o seguinte caminho base: ```plaintext /scim/v2/{accountId}/{sourceId} ``` **Parâmetros do Caminho:** - `accountId` (string): Identificador único de sua conta locatária da Cato - `sourceId` (integer): Um identificador atribuído pela Cato para representar exclusivamente uma integração IdP específica Esses parâmetros são necessários em todas as solicitações, mas são omitidos dos caminhos de endpoints individuais neste artigo por brevidade. ## Gerenciando Usuários Esta seção descreve como criar, atualizar, excluir e recuperar entidades de usuários SCIM usando a API SCIM da Cato. ### Criar um Usuário **Método HTTP:**`POST /Users` **Campos Obrigatórios:** - `userName` (string): Nome de usuário exclusivo (por exemplo, endereço de email) - `externalId` (string): Identificador externo do IdP - `active` (boolean): Deve ser `true` para ativar o usuário **Nota:**`id` é retornado pelo serviço SCIM e deve ser usado em chamadas de API subsequentes. `externalId` é opcional e não pode ser usado em caminhos de API. **Resposta:** - Status: `201 Criado` **Erros:** - `400 Solicitação Inválida`: Esquema inválido - `401 Não Autorizado` - `409 Conflito`: `userName` ou `externalId` duplicados ### Atualizar um Usuário #### PUT **Método HTTP:**`PUT /Usuários/{id}` **Campo Obrigatório:** - `id`: ID SCIM interno da Cato **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` - `404 Não Encontrado` - `409 Conflito`: `userName` ou `externalId` duplicados #### PATCH **Método HTTP:**`PATCH /Usuários/{id}` **Resposta:** - Status: `200 OK` **Erros:** - `400 Solicitação Inválida`: Esquema inválido ou sintaxe de patch - `401 Não Autorizado` - `404 Não Encontrado` - `409 Conflito`: Identificadores duplicados ### Excluir um Usuário **Método HTTP:**`DELETE /Users/{id}` **Resposta:** - Status: `204 Sem Conteúdo` Esta é uma exclusão suave. O usuário permanece no sistema, mas não é retornado nas buscas. ### Obter um Usuário pelo ID **Método HTTP:**`GET /Users/{id}` **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` - `404 Não Encontrado` ### Buscar Usuários **Método HTTP:**`GET /Users` **Parâmetros de Consulta:** - `filter`: Consulta para filtrar usuários (por exemplo, `userName eq "user@domain.com"`) - `count` (opcional) - `startIndex` (opcional) **Filtros Suportados:** - Somente `eq` é suportado - Atributos suportados: `userName`, `email`, `givenName`, `familyName` - Filtros compostos são suportados apenas neste formato: ```plaintext filter=emails[type eq "work"] e email eq "bob@cato.com" ``` **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` ## Gerenciando Grupos Esta seção explica como usar a API SCIM para criar, atualizar, excluir e recuperar entidades de grupo no seu ambiente Cato. ### Criar um Grupo **Método HTTP:**`POST /Groups` **Resposta:** - Status: `201 Criado` **Erros:** - `401 Não Autorizado` - `409 Conflito`: `displayName` ou ID de objeto duplicado ### Atualizar um Grupo #### PUT **Método HTTP:**`PUT /Groups/{id}` **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` - `404 Não Encontrado` - `409 Conflito` #### PATCH **Método HTTP:**`PATCH /Groups/{id}` **Caminhos de Patch Suportados:** - `displayName` - `members` **Resposta:** - Status: `200 OK` **Erros:** - `400 Solicitação Inválida`: Esquema inválido ou sintaxe de patch - `401 Não Autorizado` - `404 Não Encontrado` - `409 Conflito` ### Excluir um Grupo **Método HTTP:**`DELETE /Groups/{id}` **Resposta:** - Status: `204 Sem Conteúdo` > [!NOTE] > Importante: > > Esta é uma exclusão permanente. O grupo é removido permanentemente. ### Obter um Grupo por ID **Método HTTP:**`GET /Groups/{id}` **Parâmetros de Consulta Opcionais:** - `excludeAttributes` (ex.: `members`) **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` - `404 Não Encontrado` ### Procurar Grupos **Método HTTP:**`GET /Groups` **Parâmetros de Consulta:** - `filter`: Apenas `displayName eq "Nome do Grupo"` é suportado - `count` (opcional) - `startIndex` (opcional) Filtros compostos ou operadores não suportados retornam todos os grupos sem filtrar. **Resposta:** - Status: `200 OK` **Erros:** - `401 Não Autorizado` ## Notas ### Comportamento do Campo id na Criação - O campo `id` é opcional em solicitações de criação de usuários e grupos. - Se omitido, o serviço SCIM gera um `id` único. - Sempre use o valor de `id` retornado em chamadas de API subsequentes. > [!NOTE] > Importante: > > Evite usar IDs gerados pelo cliente, a menos que seja necessário. O id SCIM é o identificador autoritativo. ### Comportamento de Exclusão - **Exclusão de usuário** via `DELETE /Users/{id}` realiza uma *exclusão lógica* ao definir o campo `active` como `false`. O usuário pode ser recuperado via `GET /Users/{id}` mas está excluído dos resultados de `GET /Users`. - **Exclusão de grupo** via `DELETE /Groups/{id}` realiza uma *exclusão permanente*. O grupo é removido permanentemente.