SCIM2Client - com escopo

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 9 min. de leitura

    • A API SCIM2Client fornece métodos que chamam o sistema para o provedor de gestão de identidade entre domínios (SCIM) (função de servidor) para criar, atualizar ou excluir dados em um provedor de serviço (SP).

    O SCIM é um protocolo baseado em REST e JSON que define uma função de cliente e servidor. Um cliente geralmente é um provedor de identidade (IDP), como Okta, que contém um diretório robusto de identidades de usuário. Um SP é normalmente uma aplicação SaaS, como Box ou Slack, que precisa de um subconjunto de informações dessas identidades. Quando mudanças nas identidades são feitas no IDP, incluindo criação, atualização e exclusão, elas são sincronizadas automaticamente com o SP de acordo com o protocolo do SCIM.

    A imagem a seguir ilustra fluxos de chamada de API típicos para manipular dados do provedor de serviço.

    Fluxo de chamada de API do Cliente de SCMI

    Essa API é executada no namespace sn_auth e requer que o plug-in SCIM v2 - Cliente de gestão de identidade entre domínios da ServiceNow (com.snc.integration.scim2.client) seja instalado para acessar a API.

    Você pode localizar os resultados de cada chamada de método SCIM na tabela Logs do Cliente de SCIM [sys_scim_client_logs].

    Para obter informações adicionais sobre o SCIM, consulte Sistema para gestão de identidade entre domínios (SCIM).

    SCIM2Client - executeDelete (cadeia de caracteres do provedor, cadeia de caracteres resourceName, cadeia de caracteres providerResourceId)

    Exclui um recurso especificado de um sistema de provedor de serviço externo.

    Tabela 1. Parâmetros
    Nome Tipo Descrição
    provedor Cadeia de caracteres Obrigatório. Nome do provedor de serviço de SCIM configurado. O nome do provedor de serviço é definido no campo de nome da tabela Provedor de SCIM [sys_scim_provider].
    resourceName Cadeia de caracteres Obrigatório. Nome do tipo de recurso, como Usuário ou Grupo. Este valor está localizado no campo resource_name na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    provedorResourceId Cadeia de caracteres Obrigatório. Identificador exclusivo do recurso associado no sistema do provedor de serviço externo.
    Tabela 2. Retorna
    Tipo Descrição
    mensagem Se o status for ÊXITO, o endpoint retornará o corpo da resposta conforme definido pela REST SCIM API.

    Tipo de dados: cadeia de caracteres
    status Status da solicitação.
    Valores possíveis:
    • FALHA
    • SUCESSO

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como excluir um recurso do usuário no sistema do provedor SNOW.

    var scimClient = new sn_auth.SCIM2Client(); 
var response = scimClient.executeDelete('SNOW Provider','User','f282abf03710200044e0bfc8bcbe5d12'); 
gs.info('response: ' + response);

    Saída:

    // Example of a successful response
{
  "status":"SUCCESS",
  "message":null
}

// Example of a failed response
{
  "status":"FAILURE",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:api:messages:2.0:Error\"
    ],
    \"status\":\"404\",
    \"detail\":\"Invalid user id 3985e598876989103fa711f83cbb35ae1\"
  }"
}

    SCIM2Client – executeGet (cadeia de caracteres do provedor, cadeia de caracteres resourceName, cadeia de caracteres queryParams)

    Retorna todos os recursos de um sistema de provedor externo especificado que correspondem aos critérios aprovados.

    Essas informações são usadas para chamar a API do provedor de serviço de SCIM correspondente.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    provedor Cadeia de caracteres Obrigatório. Nome do provedor de serviço de SCIM configurado. O nome do provedor de serviço é definido no campo de nome da tabela Provedor de SCIM [sys_scim_provider].
    resourceName Cadeia de caracteres Obrigatório. Nome do tipo de recurso, como Usuário ou Grupo. Este valor está localizado no campo resource_name na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    queryParams Cadeia de caracteres Obrigatório. Parâmetros de consulta compatíveis com SCIM passados para o endpoint do provedor de serviço de SCIM externo.
    Para obter informações adicionais sobre os parâmetros de consulta disponíveis e o formato associado, consulte as seguintes seções no documento da Força-tarefa de engenharia da Internet: Sistema para gestão de identidade entre domínios: protocolo
    Tabela 4. Retorna
    Tipo Descrição
    mensagem Se o status for ÊXITO, o endpoint retornará o corpo da resposta conforme definido pela REST SCIM API.

    Tipo de dados: cadeia de caracteres
    status Status da solicitação.
    Valores possíveis:
    • FALHA
    • SUCESSO

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como recuperar todos os usuários disponíveis do provedor de serviço de teste de neve cujo e-mail comercial contém lucius.bagnoli.

    var scimClient = new sn_auth.SCIM2Client(); 
var queryParams = {}; 
queryParams['filter'] = 'emails[type eq \"work\" and value co \"lucius.bagnoli\"]'; 
var response = scimClient.executeGet('SCIM Provider Demo','User', queryParams); 
gs.info('response for get with filter: ' + response);

    Resposta:

    //Example of a successful response
{
  "status":"SUCCESS",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:api:messages:2.0:ListResponse\"
    ],
  \"totalResults\":647,
  \"Resources\":[
    {
      \"schemas\":[
        \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\",
        \"urn:ietf:params:scim:schemas:core:2.0:User\"
      ],
    \"id\":\"005d500b536073005e0addeeff7b12f4\",
    \"meta\":{
      \"resourceType\":\"User\",
      \"created\":\"2019-04-05T21:09:12Z\",
      \"lastModified\":\"2021-10-10T19:38:36Z\",
      \"location\":\"https://empiamsd1.service-now.com/api/now/scim/Users/005d500b536073005e0addeeff7b12f4\"
    },
    \"userName\":\"survey.user\",
    \"name\":{
      \"familyName\":\"user\",
      \"givenName\":\"survey\"
    },
    \"displayName\":\"survey user\",
    \"active\":true,
    \"emails\":[
      {
        \"value\":\"survey.user@email.com\",
        \"type\":\"work\"
      }
    ]
  },
  {
    \"schemas\":[
      \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\",
      \"urn:ietf:params:scim:schemas:core:2.0:User\"
    ],
    \"id\":\"02826bf03710200044e0bfc8bcbe5d3f\",
    \"meta\":{
      \"resourceType\":\"User\",
      \"created\":\"2012-02-18T03:04:49Z\",
      \"lastModified\":\"2021-10-10T19:38:36Z\",
      \"location\":\"https://empiamsd1.service-now.com/api/now/scim/Users/02826bf03710200044e0bfc8bcbe5d3f\"
    },
    \"userName\":\"lucius.bagnoli\",
    \"name\":{
      \"familyName\":\"Bagnoli\",
      \"givenName\":\"Lucius\"
    },
    \"displayName\":\"Lucius Bagnoli\",
    \"active\":true,
    \"emails\":[
      {
        \"value\":\"lucius.bagnoli@example.com\",
        \"type\":\"work\"
      }
    ],
    \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\":{
      \"gender\":\"Male\",
      \"costCenter\":{
        \"value\":\"91e8bbf43710200044e0bfc8bcbe5daa\",
        \"name\":\"Customer Support\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/CostCenters/91e8bbf43710200044e0bfc8bcbe5daa\"
      },
      \"company\":{
        \"value\":\"81fd65ecac1d55eb42a426568fc87a63\",
        \"name\":\"ACME Japan\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Companies/81fd65ecac1d55eb42a426568fc87a63\"
      },
      \"department\":{
        \"value\":\"5d7f17f03710200044e0bfc8bcbe5d43\",
        \"name\":\"Customer Support\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Departments/5d7f17f03710200044e0bfc8bcbe5d43\"
      },
      \"manager\":{
        \"value\":\"02826bf03710200044e0bfc8bcbe5d88\",
        \"displayName\":\"Billie Cowley\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Users/02826bf03710200044e0bfc8bcbe5d88\"
      },
      \"location\":{
        \"value\":\"0002c0a93790200044e0bfc8bcbe5df5\",
        \"name\":\"2-10-1 Yurakucho, Chiyoda-ku, Tokyo\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Locations/0002c0a93790200044e0bfc8bcbe5df5\"
      }
    }
  }
],
\"startIndex\":1,
\"itemsPerPage\":2}"}


// Example of a failure response
{
  "status":"FAILURE",
  "message":"SCIM Provider rest message is not configured properly"
}

    SCIM2Client – executeGetById (cadeia de caracteres do provedor, cadeia de caracteres resourceName, cadeia de caracteres providerResourceId, Mapa<String, String> queryParams)

    Retorna um recurso do sistema do provedor externo com o ID de recurso exclusivo especificado.

    Essas informações são usadas para chamar a API do provedor de serviço de SCIM correspondente.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    provedor Cadeia de caracteres Obrigatório. Nome do provedor de serviço de SCIM configurado. O nome do provedor de serviço é definido no campo de nome da tabela Provedor de SCIM [sys_scim_provider].
    provedorResourceId Cadeia de caracteres Obrigatório. Identificador exclusivo do recurso associado no sistema do provedor de serviço externo.
    queryParams Cadeia de caracteres Obrigatório. Parâmetros de consulta compatíveis com SCIM passados para o endpoint do provedor de serviço de SCIM externo.
    Para obter informações adicionais sobre os parâmetros de consulta disponíveis e o formato associado, consulte as seguintes seções no documento da Força-tarefa de engenharia da Internet: Sistema para gestão de identidade entre domínios: protocolo
    Tabela 6. Retorna
    Tipo Descrição
    mensagem Se o status for ÊXITO, o endpoint retornará o corpo da resposta conforme definido pela REST SCIM API.

    Tipo de dados: cadeia de caracteres
    status Status da solicitação.
    Valores possíveis:
    • FALHA
    • SUCESSO

    Tipo de dados: cadeia de caracteres

    Este exemplo mostra como obter o recurso especificado do "teste de neve" do sistema do provedor externo.

    var scimClient = new sn_auth.SCIM2Client(); 
var queryParams = {}; 
var response = scimClient.executeGetById('snow test','User', 'f282abf03710200044e0bfc8bcbe5d12', queryParams); 
gs.info('response for simple getById: ' + response);

    Saída:

    // Example of a successful response
{
  "status":"SUCCESS",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\",
      \"urn:ietf:params:scim:schemas:core:2.0:User\"
    ],
    \"id\":\"f282abf03710200044e0bfc8bcbe5d12\",
    \"meta\":{
      \"resourceType\":\"User\",
      \"created\":\"2012-02-18T03:04:53Z\",
      \"lastModified\":\"2021-10-10T19:38:37Z\",
      \"location\":\"https://empiamsd1.service-now.com/api/now/scim/Users/f282abf03710200044e0bfc8bcbe5d12\"
    },
    \"userName\":\"tia.neumaier\",
    \"name\":{
      \"givenName\":\"Tia\"
    },
    \"displayName\":\"Tia Neumaier\",
    \"active\":true,
    \"emails\":[
      {
        \"value\":\"tia.neumaier@example.com\",
        \"type\":\"work\"
      }
    ],
    \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\":{
      \"costCenter\":{
        \"value\":\"7fb1cc99c0a80a6d30c04574d14c0acf\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/CostCenters/7fb1cc99c0a80a6d30c04574d14c0acf\"
      },
      \"company\":{
        \"value\":\"227cdfb03710200044e0bfc8bcbe5d6b\",
        \"name\":\"ACME South America\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Companies/227cdfb03710200044e0bfc8bcbe5d6b\"
      },
      \"department\":{
        \"value\":\"221db0edc611228401760aec06c9d929\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Departments/221db0edc611228401760aec06c9d929\"
      },
      \"location\":{
        \"value\":\"25b4c23b0a0a0bb30054836629537509\",
        \"name\":\"Carretera Cancun-Chetumal KM 22, Cancun\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Locations/25b4c23b0a0a0bb30054836629537509\"
      }
    }
  }"
}

// Example of a failed response
{
  "status":"FAILURE",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:api:messages:2.0:Error\"
    ],
    \"status\":\"404\",
    \"detail\":\"User not found f282abf03710200044e0bfc8bcbe5d121\"
  }"
}

    SCIM2Client - provisionamento (cadeia de caracteres do provedor, cadeia de caracteres resourceName, cadeia de caracteres resourceId)

    Cria ou atualiza um recurso em um sistema de provedor de serviço externo para um sys_id especificado.

    Por exemplo, se você criar ou atualizar um usuário em uma instância ServiceNow, poderá usar este método para criar ou atualizar o mesmo recurso em um sistema de provedor de serviço externo. Somente os campos mapeados na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping] podem ser criados ou atualizados no recurso correspondente.

    Para obter informações adicionais sobre o mapeamento de recursos do provedor, consulte Criação de um mapeamento de recursos do provedor de SCIM.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    provedor Cadeia de caracteres Obrigatório. Nome do provedor de serviço de SCIM configurado. O nome do provedor de serviço é definido no campo de nome da tabela Provedor de SCIM [sys_scim_provider].
    resourceName Cadeia de caracteres Obrigatório. Nome do tipo de recurso, como Usuário ou Grupo. Este valor está localizado no campo resource_name na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    resourceId Cadeia de caracteres Obrigatório. Sys_id do recurso salvo na instância ServiceNow (o cliente). Este valor está localizado no campo primary_table na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    Tabela 8. Retorna
    Tipo Descrição
    mensagem Se o status for ÊXITO, o endpoint retornará o corpo da resposta conforme definido pela REST SCIM API.

    Tipo de dados: cadeia de caracteres
    status Status da solicitação.
    Valores possíveis:
    • FALHA
    • SUCESSO

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como provisionar um usuário no provedor Snow.

    var scimClient = new sn_auth.SCIM2Client(); 
var response = scimClient.provision('SNOW Provider','User','f282abf03710200044e0bfc8bcbe5d12'); 
gs.info('response: ' + response);

    Saída:

    // Example of successful response
{
  "status":"SUCCESS",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\",
      \"urn:ietf:params:scim:schemas:core:2.0:User\"
    ],
    \"id\":\"f282abf03710200044e0bfc8bcbe5d12\",
    \"meta\":{
      \"resourceType\":\"User\",
      \"created\":\"2012-02-18T03:04:53Z\",
      \"lastModified\":\"2021-10-10T19:38:37Z\",
      \"location\":\"https://empiamsd1.service-now.com/api/now/scim/Users/f282abf03710200044e0bfc8bcbe5d12\"
    },
    \"userName\":\"tia.neumaier\",
    \"name\":{
      \"familyName\":\"Neumaier\",
      \"givenName\":\"Tia\"
    },
    \"displayName\":\"Tia Neumaier\",
    \"active\":true,
    \"emails\":[
      {
        \"value\":\"tia.neumaier@example.com\",
        \"type\":\"work\"
      }
    ],
    \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\":{
      \"gender\":\"Female\",
      \"costCenter\":{
        \"value\":\"7fb1cc99c0a80a6d30c04574d14c0acf\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/CostCenters/7fb1cc99c0a80a6d30c04574d14c0acf\"
      },
      \"company\":{
        \"value\":\"227cdfb03710200044e0bfc8bcbe5d6b\",
        \"name\":\"ACME South America\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Companies/227cdfb03710200044e0bfc8bcbe5d6b\"
      },
      \"department\":{
        \"value\":\"221db0edc611228401760aec06c9d929\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Departments/221db0edc611228401760aec06c9d929\"
      },
      \"location\":{
        \"value\":\"25b4c23b0a0a0bb30054836629537509\",
        \"name\":\"Carretera Cancun-Chetumal KM 22, Cancun\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Locations/25b4c23b0a0a0bb30054836629537509\"
      }
    }
  }"
}

// Example of failure response
{
  "status":"FAILURE",
  "message":"SCIM client attribute or provider resource mapping is not configured properly , 
  No provider resource mapping id found for provider name: SNOW Provider and resource name: User"
}

    SCIM2Client - provisionNew (cadeia de caracteres do provedor, cadeia de caracteres resourceName, cadeia de caracteres resourceId)

    Cria um novo recurso em um sistema de provedor de serviço externo para um sys_id especificado.

    Por exemplo, se você criar um novo usuário em uma instância ServiceNow, poderá usar este método para criar o mesmo recurso em um sistema de provedor de serviço externo. Somente os campos mapeados na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping] podem ser criados no sistema do provedor de serviço externo correspondente. Se o recurso já estiver presente no sistema do provedor de serviço externo, uma resposta de erro será retornada.

    Para obter informações adicionais sobre o mapeamento de recursos do provedor, consulte Criação de um mapeamento de recursos do provedor de SCIM.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    provedor Cadeia de caracteres Obrigatório. Nome do provedor de serviço de SCIM configurado. O nome do provedor de serviço é definido no campo de nome da tabela Provedor de SCIM [sys_scim_provider].
    resourceName Cadeia de caracteres Obrigatório. Nome do tipo de recurso, como Usuário ou Grupo. Este valor está localizado no campo resource_name na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    resourceId Cadeia de caracteres Obrigatório. Sys_id do recurso salvo na instância ServiceNow (o cliente). Este valor está localizado no campo primary_table na tabela Mapeamento de recursos do Provedor de SCIM [sys_scim_provider_resource_mapping].
    Tabela 10. Retorna
    Tipo Descrição
    mensagem Se o status for ÊXITO, o endpoint retornará o corpo da resposta conforme definido pela REST SCIM API.

    Tipo de dados: cadeia de caracteres
    status Status da solicitação.
    Valores possíveis:
    • FALHA
    • SUCESSO

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como criar um novo usuário no provedor de serviço externo SNOW Provider.

    var scimClient = new sn_auth.SCIM2Client(); 
var response = scimClient.provisionNew('SNOW Provider','User','f282abf03710200044e0bfc8bcbe5d12'); 
gs.info('response: ' + response);

    Saída:

    // Example of successful response
{
  "status":"SUCCESS",
  "message":"{
    \"schemas\":[
      \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\",
      \"urn:ietf:params:scim:schemas:core:2.0:User\"
    ],
    \"id\":\"f282abf03710200044e0bfc8bcbe5d12\",
    \"meta\":{
      \"resourceType\":\"User\",
      \"created\":\"2012-02-18T03:04:53Z\",
      \"lastModified\":\"2021-10-10T19:38:37Z\",
      \"location\":\"https://empiamsd1.service-now.com/api/now/scim/Users/f282abf03710200044e0bfc8bcbe5d12\"
    },
    \"userName\":\"tia.neumaier\",
    \"name\":{
      \"familyName\":\"Neumaier\",
      \"givenName\":\"Tia\"
    },
    \"displayName\":\"Tia Neumaier\",
    \"active\":true,
    \"emails\":[
      {
        \"value\":\"tia.neumaier@example.com\",
        \"type\":\"work\"
      }
    ],
    \"urn:ietf:params:scim:schemas:extension:servicenow:2.0:User\":{
      \"gender\":\"Female\",
      \"costCenter\":{
        \"value\":\"7fb1cc99c0a80a6d30c04574d14c0acf\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/CostCenters/7fb1cc99c0a80a6d30c04574d14c0acf\"
      },
      \"company\":{
        \"value\":\"227cdfb03710200044e0bfc8bcbe5d6b\",
        \"name\":\"ACME South America\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Companies/227cdfb03710200044e0bfc8bcbe5d6b\"
      },
      \"department\":{
        \"value\":\"221db0edc611228401760aec06c9d929\",
        \"name\":\"Sales\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Departments/221db0edc611228401760aec06c9d929\"
      },
      \"location\":{
        \"value\":\"25b4c23b0a0a0bb30054836629537509\",
        \"name\":\"Carretera Cancun-Chetumal KM 22, Cancun\",
        \"$ref\":\"https://empiamsd1.service-now.com/api/now/scim/Locations/25b4c23b0a0a0bb30054836629537509\"
      }
    }
  }"
}

// Example of failure response
{
  "status":"FAILURE",
  "message":"SCIM client attribute or provider resource mapping is not configured properly , 
  No provider resource mapping id found for provider name: SNOW Provider and resource name: User"
}