Endpoints da API do servidor SCIM do Drupal
Visão geral
Este documento descreve os endpoints SCIM necessários para habilitar o provisionamento e o desprovisionamento de usuários SCIM. SCIM é um protocolo padrão do setor que permite automatizar as operações CRUD (criar, atualizar, excluir e atualizar) de usuários. Usando o módulo , o site Drupal poderá atuar como servidor SCIM. Isso significa que quaisquer alterações feitas no provedor de identidade (ou seja, o cliente SCIM) serão sincronizadas com o site Drupal.
Visão geral do SCIM
- Versão do protocolo: SCIM 2.0
- Caminho base: base_url/scim
- Recursos disponíveis: Usuários, Grupos
- Formato de dados: JSON
Autenticação e cabeçalhos
- Autorização: Token de portador
- Tipo de conteúdo: aplicação / json
- Aceitar: aplicação / json
Operações de API suportadas
As seguintes operações de API são suportadas.
Pontos de extremidade do usuário
- Desativar usuário
- Obter usuário
- Lista de usuários
- Atualização do usuário (PATCH)
- Atualizar usuário (PUT)
- Criar usuário (POST)
Pontos finais do grupo
- Listar grupos
- Obter grupo por ID
- Criar um Grupo
- Atualizar grupo [Atributos de não membros]
- Grupo de atualização [Membros]
- Excluir grupo
Pontos de extremidade do usuário
1. Desativar usuário (PATCH)
- Erros:
- Solicitação de exemplo:
- Exemplo de resposta - 204 Sem conteúdo.
Para desativar ou excluir um usuário no Drupal, você precisa habilitar as configurações necessárias no módulo. Essas opções estão disponíveis na página de configuração do módulo.
PATCH /Users/{user-id}| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de recurso não encontrado | O usuário especificado não existe. | 404 |
PATCH /Users/{user-id} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "Operações": [ { "op": "Substituir", "caminho": "ativo", "valor": falso } ] }
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "4", "userName": "username", "active": , "emails": [{ "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" }], "meta": { "resourceType": "User" } }
2. Pesquisar usuário pelo seu ID
- Erros:
- Solicitação de exemplo:
- Resposta de exemplo:
- 404 não encontrado.
- 200 Ok encontrados.
Para obter um usuário existente, faça uma solicitação GET para /Users usando o ID do usuário.
GET /Users/{user-id}| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de recurso não encontrado | O usuário especificado não existe. | 404 |
GET /Users/{user-id} HTTP/1.1 Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Usuário não encontrado", "status": 404 }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "4", "userName": "username", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
3. Listar usuários
- Erros:
- Parâmetros de consulta:
- Solicitação de exemplo:
- Resposta de exemplo:
- Solicitação de exemplo:
- Resposta de exemplo:
- Se o usuário não for encontrado com o nome de usuário, enviamos um esquema vazio indicando que nenhum usuário foi encontrado.
- Solicitação de exemplo:
- Resposta de exemplo:
- Se o usuário apresentar o e-mail.
- Caso o usuário não seja encontrado pelo e-mail, o módulo envia um esquema vazio indicando que o usuário não foi encontrado.
Este endpoint permite filtrar e recuperar usuários específicos da lista de usuários existente. Ao fazer uma requisição GET para o endpoint /Users e adicionar parâmetros de filtro, você pode refinar os resultados com base em atributos como nome de usuário e e-mail. O endpoint suporta buscas filtradas, mas pode retornar no máximo 50 registros de usuários por requisição.
| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de recurso não encontrado | O usuário especificado não existe. | 404 |
OBTER /Usuários
3.1 Índice inicial e contagem
Permite que os parâmetros de consulta sejam startIndex e count. Onde startIndex será o ID inicial e count será o número máximo de resultados que a consulta pode retornar.
GET /Users?startIndex=1&count=50 Autorização: Portador
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 2, "startIndex": 1, "itemsPerPage": 2, "Resources": [ { "id": "1", "externalId": "1", "meta": { "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "example1@example.com", "displayName": "example1@example.com", "emails": { "value": "example1@example.com", "type": "work", "primary": true }, "active": true, "name": { "familyName": "", "givenName": "" }, "groups": [ "authenticated,administrator" ], "department": "" }, { "id": "13", "externalId": "13", "meta": { "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "example2", "displayName": "example2", "emails": { "value": "example2@example.com", "type": "work", "primary": true }, "active": true, "name": { "familyName": "", "givenName": "" }, "groups": [ "authenticated,administrator" ], "department": "" }, ] }
3.2 Pesquisar um usuário pelo seu nome de usuário
GET /Users?filter=userName eq "admin"
Usuário não encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
Usuário encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid do usuário", "username": "admin", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
3.3 Pesquisar o usuário pelo endereço de e-mail
GET /Users?filter=emails[type eq "work"].value eq "email@gmail.com" Authorization: Bearer
Usuário encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid do usuário", "username": "Nome de usuário", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
Usuário não encontrado - 200 Ok.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
4. Atualização do usuário (PATCH)
Se o usuário for encontrado na requisição GET, uma requisição PATCH ou PUT será feita para atualizá-lo; caso contrário, uma requisição POST será feita para criar o usuário. Você pode atualizar campos específicos de um usuário usando uma requisição PATCH para o endpoint /Users . No corpo da requisição, inclua o atributo que deseja alterar e seu valor atualizado.
PATCH /Users/{user-id}- Erros:
- Solicitação de exemplo:
- Exemplo de resposta: 200 OK.
| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de recurso não encontrado | O usuário especificado não existe. | 404 |
PATCH/Users/{{user-id}} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "Replace", "path": "emails[type eq \"work\"].value", "value": "email@gmail.com" }, { "op": "Replace", "path": "name.familyName", "value": "familyname" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid do usuário", "userName": "Nome de usuário", "active": 1, "emails": [ { "primary": true, "value": "email@gmail.com", "type": "work", "display": "email@gmail.com" } ], "meta": { "resourceType": "User" } }
5. Atualizar usuário (PUT)
Você pode atualizar um usuário usando uma requisição PUT para o endpoint /Users . Essa requisição substitui o objeto de usuário inteiro, portanto, todos os atributos de usuário necessários devem ser fornecidos no corpo da requisição.
PUT /Users/{{user-id}}- Erros:
- Solicitação de exemplo:
- Exemplo de resposta: 200 ok.
| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de recurso não encontrado | O usuário especificado não existe. | 404 |
PUT/Users/{{user-id}} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "exmple", "active": 1, "emails": [ { "primary": true, "value": "exmple@example.com", "type": "work", "display": "exmple@example.com" } ], "meta": { "resourceType": "User" }, "name": { "givenName": "givenName", "familyName": "familyName", "middleName": "sdf", "honorificPrefix": "sdf" }, "displayName": "givenName familyName", "nickName": "df", "addresses": [ { "primary": true, "locality": "fdd" } ], "locale": "en-US", "externalId": "9rqltOOLI95d7", "groups": [] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "example", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
6. Criar usuário (POST)
Utilize uma requisição POST no endpoint /Users para criar um novo usuário. Certifique-se de incluir todos os campos necessários no corpo da requisição. Uma requisição bem-sucedida retorna o código 201 Created e os detalhes do usuário.
POST /Usuários
- Erros:
- Solicitação de exemplo:
- Exemplo de resposta: 201 criado.
| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| Exceção de Conflito | O usuário já existe. | 409 |
POST /Users HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"], "externalId": "abc", "userName": "example", "active": true, "emails": [{ "primary": true, "type": "work", "value": "example@example.com" }], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" } }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "externalId": "abc", "userName": "example", "active": true, "emails": [ { "primary": true, "type": "work", "value": "example@example.com" } ], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" }, "id": "98" }
Pontos finais do grupo
1. Listar grupos
O endpoint /Groups suporta requisições GET para recuperar uma lista de grupos disponíveis no servidor SCIM. Essa operação retorna apenas as informações básicas do grupo, como o ID e o nome de exibição. A lista de membros é sempre retornada vazia, pois o endpoint não inclui detalhes de associação a grupos na resposta.
- Solicitação de exemplo:
- Exemplo de resposta - 200 ok
- Filtro suportado:
- Solicitação de exemplo:
- Exemplo de resposta: 200 ok.
GET /Groups HTTP/1.1 Autorização: Bearer
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 4, "Resources": [ { "id": "anonymous", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "anonymous" }, { "id": "authenticated", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "authenticated" }, { "id": "administrator", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "administrator" }, { "id": "editor_admin", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "editor_admin" } ], "startIndex": 1, "itemsPerPage": 4 }
GET /Groups?filter=displayName eq "administrator"
GET /scim/Groups?filter=displayName eq "administrator" HTTP/1.1 Authorization: Bearer
Se um grupo for encontrado com o nome de exibição.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "Resources": [], "startIndex": 1, "itemsPerPage": 20 }
2. Pesquisar grupo por ID
/Groups/{id} recupera o recurso de grupo associado ao ID de grupo fornecido. Somente os metadados do grupo são retornados na resposta. Detalhes de associação não são incluídos.
- Solicitação de exemplo:
- Resposta de exemplo:
GET /Groups/administrator HTTP/1.1 Authorization: Bearer
Encontrado - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "administrator", "meta": { "resourceType": "Group" }, "displayName": "Administrator" }
Não encontrado - 404.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Administrador do grupo não encontrado", "status": 404 }
3. Crie um grupo
Use uma requisição POST para /Groups para criar um novo grupo. Você precisa fornecer um nome para o grupo (displayName). Embora você possa incluir membros no corpo da requisição, a resposta sempre retornará uma lista vazia de membros.
- Erros:
- Solicitação de exemplo:
- Solicitação sem lista de membros incluída.
- Solicitar lista de membros.
- Resposta: 201 Criado.
| erro | Condição | Código de status HTTP |
|---|---|---|
| Exceção de Validação | Ou o módulo não está ativado, ou está sendo usada uma chave de licença incorreta. | 400 |
| Exceção não autorizada | O cabeçalho de autorização é inválido ou está ausente. | 401 |
| OperationNotSupportedException | Não é permitida a modificação do grupo. | 501 |
POST /Groups HTTP/1.1 Autorização: Bearer { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "externalId": "enternal-id", "displayName": "group2", "meta": { "resourceType": "Group" } }
POST /Groups HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "group1", "members": [ { "value": "3", "display": "admin@gmail.com" }, { "value": "2", "display": "admin2@gmail.com" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "externalId": "enternal-id", "displayName": "group2", "meta": { "resourceType": "Group" }, "members": [], "id": "group2" }
4. Atualizar grupo [Atributos de não membros]
Você pode atualizar os detalhes básicos de um grupo, como o nome de exibição, usando uma solicitação PATCH para /Groups/{group-id} . Essa solicitação atualiza apenas os atributos que você fornecer e não altera os membros do grupo. Uma atualização bem-sucedida retorna o código 204 Sem Conteúdo.
- Solicitação de exemplo:
- Exemplo de resposta - 204 Sem conteúdo.
PATCH /Groups/group1 HTTP/1.1 Authorization: Bearer{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Replace", "path": "displayName", "value": "updated group1" }] }
5. Atualizar grupo [Membros]
O endpoint /Groups/{id} permite adicionar e remover membros por meio de uma requisição PATCH. O corpo da requisição deve incluir a lista de IDs de usuário que você deseja adicionar. Esta ação atualiza apenas os membros do grupo e retorna o código 204 No Content em caso de sucesso.
- Solicitação de exemplo:
- Adicionar um membro ao grupo.
- Remova o membro do grupo.
- Exemplo de resposta: 204 Sem conteúdo.
PATCH /Groups/updated group1 HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Add", "path": "members", "value": [{ "$ref": null, "value": "97" }] }] }
PATCH /Groups/updated group1 HTTP/1.1 Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Remover", "path": "members", "value": [{ "$ref": null, "value": "97" }] }] }
6. Excluir grupo
O endpoint /Groups/{id} permite excluir um grupo usando uma solicitação DELETE . Essa operação remove o grupo do servidor SCIM. Uma exclusão bem-sucedida retorna uma resposta 204 No Content , indicando que o grupo foi excluído, e nenhum corpo de resposta é fornecido.
- Solicitação de exemplo:
- Exemplo de resposta - 204 Sem conteúdo.
DELETE /Groups/updated group1 HTTP/1.1 Authorization: Bearer
Caso a configuração não tenha sido bem-sucedida, entre em contato conosco pelo endereço drupalsupport@xecurify.com. Envie uma captura de tela da janela de erro e nós o ajudaremos a resolver o problema e o guiaremos durante a configuração.
