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.

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.

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:

Authorization: Bearer <access_token>
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:

/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:

  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

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.

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.