Pular para o conteúdo principal

Cosafe Support Center


Exemplos de envio de solicitações SCIM

Important

Este artigo fornece exemplos de solicitações de endpoint SCIM que a API suporta. Seu provedor de identidade (IdP) normalmente lida com essas solicitações automaticamente, portanto, a interação manual geralmente é desnecessária.

Utilize estes exemplos somente se estiver criando um conector personalizado e precisar testá-lo em relação à API SCIM. Conectores personalizados podem produzir resultados instáveis ou imprevisíveis se apresentarem comportamento inesperado, por isso geralmente desencorajamos a criação de conectores do zero. No entanto, se a sua situação exigir integração manual e você não puder usar um conector de terceiros pré-configurado, consulte estes exemplos para obter orientações.

URL base​

Utilize o URL base fornecido durante a ativação do complemento SCIM. Os exemplos neste documento referem-se a isto como <base-url>.

Cabeçalhos​

Todas as solicitações devem incluir os seguintes cabeçalhos:

'Authorization': 'Bearer <your-api-key>',
'Content-Type': 'application/scim+json; charset=utf-8',

Para simplificar, os exemplos a seguir mostram apenas a URL e o corpo da solicitação.

Limitações​

  • Número máximo de paginação: 1000
  • Comprimento máximo do atributo members para solicitações: 1000
  • O método GET filter suporta apenas um atributo com a operação eq (igual).

Pontos finais de leitura​

Listar todos os usuários​

GET <base-url>/Users

Resposta:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "value": "john@example.com",
          "primary": verdadeiro
        }
      ],
      "displayName": "John Doe",
      "phoneNumbers": [
        {
          "primary": true,
          "value": "+467017406351",
          "type": "work"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Liste todos os grupos​

OBTER <base-url>/Grupos

Resposta:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "8e9d1a59-bbe5-11f0-90fb-3e40deb6141c",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Encontrar usuário existente​

GET <base-url>/Users?filter=userName eq "john@example.com"

Para verificar se um usuário já existe no sistema e recuperar seu id para solicitações subsequentes, use o parâmetro filter com o atributo correspondente userName para encontrar o usuário pelo seu nome exclusivo.

Se o usuário existir, o endpoint retorna o esquema do usuário contendo o atributo id, que você usa para todas as solicitações subsequentes para esse usuário:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1,
  "Resources": [
    {
      "active": true,
      "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
      "userName": "john@example.com",
      "emails": [
        {
          "valor": "john@example.com",
          "principal": true
        }
      ],
      "nome de exibição": "John Doe",
      "números de telefone": [
        {
          "principal": true,
          "valor": "+46701740635",
          "tipo": "trabalho"
        },
        {
          "primary": false,
          "value": "+46313900642",
          "type": "mobile"
        }
      ]
    }
  ]
}

Se o usuário não existir, o endpoint retorna 200 OK com uma lista vazia.

Obtenha um usuário​

Recupere um usuário existente fazendo uma solicitação GET para o endpoint /Users com o id do usuário.

GET <base-url>/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "8693b7d1-afe8-11f0-8cc2-3a7cb373875a",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/8693b7d1-afe8-11f0-8cc2-3a7cb373875a"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+46701740635",
      "type": "work"
    },
    {
      "primary": false,
      "value": "+46313900642",
      "type": "mobile"
    }
  ]
}

Utilize este endpoint para verificar se o usuário ainda existe no sistema ou para verificar se há atributos incompatíveis.

Encontre um grupo existente​

Utilize o atributo externalId para encontrar um grupo. Para obter instruções sobre como configurar o campo ID do grupo no painel de administração, consulte Configurando grupos.

GET <base-url>/Groups?filter=externalId eq "b55a6bbf-fcc1-4d06-943e-896d963b649a"

Resposta:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
      "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
      "displayName": "West county -- all-staff"
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 20,
  "totalResults": 1
}

Considerações importantes:

  • Se este endpoint retornar "totalResults": 2 (ou qualquer valor maior que 1), considere que a associação falhou e não tente usar o primeiro elemento da lista como o usuário correspondente.
  • Caso o grupo não seja encontrado, crie um grupo no Painel de Administração do Cosafe e defina o ID do grupo como o ID interno do seu sistema. Este campo passa a ser o atributo externalId.
  • O atributo members está excluído desta lista. Para recuperar membros, use o endpoint de obtenção de grupo.
  • Se a resposta não contiver o atributo externalId, o ID do grupo não está configurado corretamente no painel de administração. Consulte Configurando grupos.

Forme um grupo​

Recupere um grupo existente fazendo uma solicitação GET para o endpoint /Groups com o id do grupo.

OBTER <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- all-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

O atributo members contém uma lista de IDs de usuário (id) pertencentes a esse grupo como value.

No nome do grupo, o prefixo "West County" não faz parte do nome do grupo. É o nome da subconta à qual o grupo pertence. Esse prefixo é adicionado para IdPs que precisam distinguir os grupos retornados por seu displayName, já que diferentes subcontas geralmente contêm grupos com nomes idênticos.

Criar pontos de extremidade​

Criar um usuário​

POST <base-url>/Usuários

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "active": true,
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "phoneNumbers": [
    { "primary": true, "type": "work", "value": "+46701740635" },
    { "primary": false, "type": "mobile", "value": "+46313900642" }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe",
  "title": "Teacher",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "work",
      "primary": true
    },
    {
      "value": "+46313900642",
      "type": "mobile",
      "primary": false
    }
  ]
}

A resposta inclui o atributo id, que você utiliza em todas as solicitações subsequentes para este usuário.

Criar um grupo​

Para criar um grupo, crie-o no Painel de Administração do Cosafe e defina o ID do grupo como o seu ID de sistema interno, que se tornará o externalId.

Atualizar endpoints​

O método preferencial para modificar um recurso é usar uma solicitação PATCH com uma operação no atributo.

Atualizar um grupo​

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "senior-staff"
    }
  ]
}

A solicitação de operação PATCH pode conter várias operações.

Esta solicitação substitui "todos os funcionários" por "funcionários seniores".

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" }
  ]
}

Atualizar membros do grupo​

Você pode atualizar os membros do grupo usando duas abordagens:

1. Atualização parcial (adicionar ou remover usuários específicos)​

Adicionando membros:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

O elemento value é o id do usuário.

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Removendo membros:

PATCH <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members",
      "value": [
        { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
        { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
      ]
    }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" }
  ]
}

2. Substitua toda a matriz de membros​

Se preferir substituir toda a matriz de membros, use uma solicitação PUT.

Nota: Esta abordagem não é recomendada para grupos com um grande número de membros. Por motivos de desempenho, utilize atualizações parciais por meio de operações de adição/remoção, incluindo apenas as alterações nas associações, inclusive durante a população inicial do grupo.

PUT <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "displayName": "senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "valor": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "valor": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "valor": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "valor": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "19bd0074-9879-11f0-907c-3ec688ae4630",
  "externalId": "b55a6bbf-fcc1-4d06-943e-896d963b649a",
  "meta": {
    "resourceType": "Group",
    "location": "/core/v1/scim/v2/Groups/19bd0074-9879-11f0-907c-3ec688ae4630"
  },
  "displayName": "West county -- senior-staff",
  "members": [
    { "value": "86954066-afe8-11f0-8cc2-3a7cb373875a" },
    { "value": "cad12528-b981-11f0-93b9-ca6e7f736f08" },
    { "value": "e6a5a88a-b980-11f0-93b9-ca6e7f736f08" },
    { "value": "5e2612e1-0d52-4261-ba00-46c144bcdf46" },
    { "value": "93025edd-af0d-4f04-8883-98d779469c50" }
  ]
}

Atualizar atributos simples do usuário​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "John Doe Jr."
    }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Professor",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "trabalho",
      "primário": verdadeiro
    },
    {
      "valor": "+46313900642",
      "tipo": "móvel",
      "primário": falso
    }
  ]
}

Atualizar atributos multivalorados do usuário​

1. Substituir números de telefone​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [
        { "primary": true, "value": "+46701740635" },
        { "primary": false, "value": "+46406280473" }
      ]
    }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Professor",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "trabalho",
      "primário": verdadeiro
    },
    {
      "valor": "+46406280473",
      "tipo": "móvel",
      "primário": falso
    }
  ]
}

2. Substituir números de telefone por remoção​

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers",
      "value": [{ "primary": true, "value": "+46701740635" }]
    }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Professor",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "trabalho",
      "primário": verdadeiro
    },
    {
      "valor": "",
      "tipo": "móvel",
      "primário": falso
    }
  ]
}

3. Formato compatível com Entra​

A API também suporta o formato enviado pela Entra:

PATCH <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Corpo da solicitação:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "phoneNumbers[type eq \"mobile\"].value",
      "value": "+46980319247"
    }
  ]
}

Resposta:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "de11042f-bbb5-11f0-90fb-3e40deb6141c",
  "meta": {
    "resourceType": "User",
    "location": "/core/v1/scim/v2/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c"
  },
  "userName": "john@example.com",
  "displayName": "John Doe Jr.",
  "title": "Professor",
  "active": true,
  "emails": [
    {
      "value": "john@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+46701740635",
      "type": "trabalho",
      "primário": verdadeiro
    },
    {
      "valor": "+46980319247",
      "tipo": "móvel",
      "primário": falso
    }
  ]
}

Excluir pontos de extremidade​

Excluir um usuário​

EXCLUIR <base-url>/Users/de11042f-bbb5-11f0-90fb-3e40deb6141c

Resposta:

204 Sem conteúdo

Solicitações GET subsequentes para este recurso por ID retornarão 404 Não encontrado.

Excluir um grupo​

EXCLUIR <base-url>/Groups/19bd0074-9879-11f0-907c-3ec688ae4630

Resposta:

204 Sem conteúdo

Solicitações GET subsequentes para este recurso por ID retornarão 404 Não encontrado.