SCIM2Client - Dans le champ d’application

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 9 minutes de lecture

    • L’API SCIM2Client fournit des méthodes qui appellent le fournisseur System for Cross-domain Identity Management (SCIM) (rôle serveur) pour créer, mettre à jour ou supprimer des données dans un fournisseur de service (SP).

    SCIM est un protocole REST et JSON qui définit un rôle client et serveur. Un client est généralement un fournisseur d’identité (IDP), tel Oktaque , qui contient un répertoire robuste d’identités d’utilisateur. Un SP est généralement une SaaS application, telle que Box ou Slack, qui a besoin d’un sous-ensemble d’informations provenant de ces identités. Lorsque des changements d’identités sont apportés dans l’IDP, y compris la création, la mise à jour et la suppression, ils sont automatiquement synchronisés avec le SP conformément au protocole SCIM.

    L’image suivante illustre des flux d’appel d’API typiques pour la manipulation des données du fournisseur de service.

    Flux d’appel de l’API du client SCMI

    Cette API s’exécute dans l’espace de noms sn_auth et nécessite l’installation du module d’extension SCIM v2 - ServiceNow Cross-domain Identity Management Client (com.snc.integration.scim2.client) pour accéder à l’API.

    Vous pouvez localiser les résultats de chaque appel de méthode SCIM dans la table Journaux clients SCIM [sys_scim_client_logs].

    Pour plus d’informations sur SCIM, consultez System for Cross-domain Identity Management (SCIM).

    SCIM2Client : executeDelete (chaîne fournisseur, chaîne resourceName, chaîne providerResourceId)

    Supprime une ressource spécifiée d’un système de fournisseur de service externe.

    Tableau 1. Paramètres
    Nom Type Description
    fournisseur Chaîne Requis. Nom du fournisseur de service SCIM configuré. Le nom du fournisseur de service est défini dans le champ Nom de la table Fournisseur SCIM [sys_scim_provider].
    resourceName Chaîne Requis. Nom du type de ressource, par exemple Utilisateur ou Groupe. Cette valeur figure dans le champ resource_name de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    providerResourceId (en anglais seulement) Chaîne Requis. Identificateur unique de la ressource associée sur le système du fournisseur de service externe.
    Tableau 2. Renvoie
    Type Description
    message Si la status valeur est RÉUSSITE, le point de terminaison renvoie le corps de la réponse tel que défini par l’API REST SCIM .

    Type de données : chaîne
    statut État de la demande.
    Valeurs possibles :
    • ÉCHEC
    • SUCCÈS

    Type de données : chaîne

    L’exemple suivant montre comment supprimer une ressource utilisateur dans le système SNOW Provider.

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

    Sortie :

    // 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 (chaîne fournisseur, chaîne resourceName, chaîne queryParams)

    Renvoie toutes les ressources d’un système de fournisseur externe spécifié qui correspondent aux critères réussis.

    Ces informations sont utilisées pour appeler l’API du fournisseur de services SCIM correspondant.

    Tableau 3. Paramètres
    Nom Type Description
    fournisseur Chaîne Requis. Nom du fournisseur de service SCIM configuré. Le nom du fournisseur de service est défini dans le champ Nom de la table Fournisseur SCIM [sys_scim_provider].
    resourceName Chaîne Requis. Nom du type de ressource, par exemple Utilisateur ou Groupe. Cette valeur figure dans le champ resource_name de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    queryParams Chaîne Requis. Paramètres de requête conformes à la norme SCIM transmis au point de terminaison du fournisseur de service SCIM externe.
    Pour plus d’informations sur les paramètres de requête disponibles et leur format associé, reportez-vous aux sections suivantes du document Internet Engineering Task Force : System for Cross-domain Identity Management : Protocol
    Tableau 4. Renvoie
    Type Description
    message Si la status valeur est RÉUSSITE, le point de terminaison renvoie le corps de la réponse tel que défini par l’API REST SCIM .

    Type de données : chaîne
    statut État de la demande.
    Valeurs possibles :
    • ÉCHEC
    • SUCCÈS

    Type de données : chaîne

    L’exemple suivant montre comment récupérer tous les utilisateurs disponibles à partir du fournisseur de service de test de neige dont l’e-mail professionnel contient 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);

    Réponse :

    //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 (chaîne fournisseur, chaîne resourceName, chaîne providerResourceId, Map<String, chaîne> queryParams)

    Renvoie une ressource du système du fournisseur externe avec l’ID de ressource unique spécifié.

    Ces informations sont utilisées pour appeler l’API du fournisseur de services SCIM correspondant.

    Tableau 5. Paramètres
    Nom Type Description
    fournisseur Chaîne Requis. Nom du fournisseur de service SCIM configuré. Le nom du fournisseur de service est défini dans le champ Nom de la table Fournisseur SCIM [sys_scim_provider].
    providerResourceId (en anglais seulement) Chaîne Requis. Identificateur unique de la ressource associée sur le système du fournisseur de service externe.
    queryParams Chaîne Requis. Paramètres de requête conformes à la norme SCIM transmis au point de terminaison du fournisseur de service SCIM externe.
    Pour plus d’informations sur les paramètres de requête disponibles et leur format associé, reportez-vous aux sections suivantes du document Internet Engineering Task Force : System for Cross-domain Identity Management : Protocol
    Tableau 6. Renvoie
    Type Description
    message Si la status valeur est RÉUSSITE, le point de terminaison renvoie le corps de la réponse tel que défini par l’API REST SCIM .

    Type de données : chaîne
    statut État de la demande.
    Valeurs possibles :
    • ÉCHEC
    • SUCCÈS

    Type de données : chaîne

    Cet exemple montre comment obtenir la ressource spécifiée à partir du système de fournisseur externe « snow test ».

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

    Sortie :

    // 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 : mise en service (chaîne fournisseur, chaîne resourceName, chaîne resourceId)

    Crée ou met à jour une ressource dans le système d’un fournisseur de service externe pour un sys_id spécifié.

    Par exemple, si vous créez ou mettez à jour un utilisateur dans une ServiceNow instance, vous pouvez utiliser cette méthode pour créer ou mettre à jour la même ressource sur le système d’un fournisseur de service externe. Seuls les champs mappés dans la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping ] peuvent être créés ou mis à jour dans la ressource correspondante.

    Pour plus d’informations sur le mappage des ressources du fournisseur, consultez Créer un mappage des ressources du fournisseur SCIM.

    Tableau 7. Paramètres
    Nom Type Description
    fournisseur Chaîne Requis. Nom du fournisseur de service SCIM configuré. Le nom du fournisseur de service est défini dans le champ Nom de la table Fournisseur SCIM [sys_scim_provider].
    resourceName Chaîne Requis. Nom du type de ressource, par exemple Utilisateur ou Groupe. Cette valeur figure dans le champ resource_name de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    resourceId Chaîne Requis. Sys_id de la ressource enregistrée dans l’instance ServiceNow (le client). Cette valeur figure dans le champ primary_table de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    Tableau 8. Renvoie
    Type Description
    message Si la status valeur est RÉUSSITE, le point de terminaison renvoie le corps de la réponse tel que défini par l’API REST SCIM .

    Type de données : chaîne
    statut État de la demande.
    Valeurs possibles :
    • ÉCHEC
    • SUCCÈS

    Type de données : chaîne

    L’exemple suivant montre comment mettre en service un utilisateur sur Snow Provider.

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

    Sortie :

    // 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 (chaîne fournisseur, chaîne resourceName, chaîne resourceId)

    Crée une nouvelle ressource dans un système de fournisseur de service externe pour un sys_id spécifié.

    Par exemple, si vous créez un nouvel utilisateur dans une ServiceNow instance, vous pouvez utiliser cette méthode pour créer la même ressource sur un système de fournisseur de service externe. Seuls les champs mappés dans la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping] peuvent être créés dans le système du fournisseur de service externe correspondant. Si la ressource est déjà présente dans le système du fournisseur de service externe, une réponse d’erreur est renvoyée.

    Pour plus d’informations sur le mappage des ressources du fournisseur, consultez Créer un mappage des ressources du fournisseur SCIM.

    Tableau 9. Paramètres
    Nom Type Description
    fournisseur Chaîne Requis. Nom du fournisseur de service SCIM configuré. Le nom du fournisseur de service est défini dans le champ Nom de la table Fournisseur SCIM [sys_scim_provider].
    resourceName Chaîne Requis. Nom du type de ressource, par exemple Utilisateur ou Groupe. Cette valeur figure dans le champ resource_name de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    resourceId Chaîne Requis. Sys_id de la ressource enregistrée dans l’instance ServiceNow (le client). Cette valeur figure dans le champ primary_table de la table Mappage des ressources du fournisseur SCIM [sys_scim_provider_resource_mapping].
    Tableau 10. Renvoie
    Type Description
    message Si la status valeur est RÉUSSITE, le point de terminaison renvoie le corps de la réponse tel que défini par l’API REST SCIM .

    Type de données : chaîne
    statut État de la demande.
    Valeurs possibles :
    • ÉCHEC
    • SUCCÈS

    Type de données : chaîne

    L’exemple suivant montre comment créer un nouvel utilisateur dans le fournisseur de services externe SNOW Provider.

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

    Sortie :

    // 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"
}