SCIM2Client : Bereichsbezogen

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 7 Minuten Lesedauer

    • Die SCIM2Client- API bietet Methoden, die den Anbieter des System for Cross-Domain Identity Management (SCIM) (Serverrolle) aufrufen, um Daten in einem Service Provider (SP) zu erstellen, zu aktualisieren oder zu löschen.

    SCIM ist ein auf REST und JSON basierendes Protokoll, das eine Client- und eine Serverrolle definiert. Ein Client ist normalerweise ein Identitätsanbieter (IDP) wie Okta, der ein robustes Verzeichnis von Benutzeridentitäten enthält. Ein SP ist normalerweise eine SaaS -Anwendung, z. B. Box oder Slack, die eine Teilmenge von Informationen von diesen Identitäten benötigt. Wenn im IdP Änderungen an Identitäten vorgenommen werden (z. B. Erstellen, Aktualisieren und Löschen), werden sie gemäß dem SCIM-Protokoll automatisch mit dem SP synchronisiert.

    Die folgende Abbildung zeigt typische API-Aufruf-Flows zur Bearbeitung von Service Provider-Daten.

    Flow für SCMI-Client-API-Aufrufe

    Diese API wird im Namespace sn_auth ausgeführt und erfordert die Installation des Plugins „SCIM v2 - ServiceNow Cross-domain Identity Management Client“ (com.snc.integration.scim2.client), um auf die API zugreifen zu können.

    Sie können die Ergebnisse der einzelnen SCIM-Methodenaufrufe in der Tabelle „SCIM-Clientprotokolle“ [sys_scim_client_logs] finden.

    Weitere Informationen zu SCIM finden Sie unter System für domänenübergreifendes Identitätsmanagement (SCIM).

    SCIM2Client - executeDelete (Zeichenfolge-Provider, Zeichenfolge resourceName, Zeichenfolge providerResourceId)

    Löscht eine angegebene Ressource aus dem System eines externen Service Providers.

    Tabelle : 1. Parameter
    Name Typ Beschreibung
    Anbieter Zeichenfolge Erforderlich. Name des konfigurierten SCIM-Service Providers Der Name des Service Providers wird im Namensfeld der Tabelle „SCIM-Provider“ [sys_scim_provider] definiert.
    resourceName Zeichenfolge Erforderlich. Name des Ressourcentyps, z. B. Benutzer oder Gruppe.

    Tabelle: Im Feld resource_name der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    providerResourceId Zeichenfolge Erforderlich. Eindeutiger Bezeichner der zugeordneten Ressource im System des externen Service Providers.
    Tabelle : 2. Rückgaben
    Typ Beschreibung
    Nachricht Wenn status ERFOLGREICH ist, gibt der Endpunkt den Antworttext gemäß der REST- SCIM- API zurück.

    Datentyp: Zeichenfolge
    status Status der Anforderung.
    Mögliche Werte:
    • FEHLER
    • ERFOLG

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie eine Benutzerressource im System des SNOW-Anbieters gelöscht wird.

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

    Ausgabe:

    // 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 (Zeichenfolge Provider, Zeichenfolge resourceName, Zeichenfolge queryParams)

    Gibt alle Ressourcen aus einem angegebenen externen Anbietersystem zurück, die den übergebenen Kriterien entsprechen.

    Diese Informationen werden verwendet, um die entsprechende API des SCIM-Service Providers aufzurufen.

    Tabelle : 3. Parameter
    Name Typ Beschreibung
    Anbieter Zeichenfolge Erforderlich. Name des konfigurierten SCIM-Service Providers Der Name des Service Providers wird im Namensfeld der Tabelle „SCIM-Provider“ [sys_scim_provider] definiert.
    resourceName Zeichenfolge Erforderlich. Name des Ressourcentyps, z. B. Benutzer oder Gruppe.

    Tabelle: Im Feld resource_name der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    queryParams Zeichenfolge Erforderlich. SCIM-konforme Abfrageparameter, die an den Endpunkt des externen SCIM-Service Providers übergeben werden.
    Weitere Informationen zu den verfügbaren Abfrageparametern und dem zugehörigen Format finden Sie in den folgenden Abschnitten im Dokument der Internet Engineering Task Force: System für domänenübergreifendes Identitätsmanagement: Protokoll
    Tabelle : 4. Rückgaben
    Typ Beschreibung
    Nachricht Wenn status ERFOLGREICH ist, gibt der Endpunkt den Antworttext gemäß der REST- SCIM- API zurück.

    Datentyp: Zeichenfolge
    status Status der Anforderung.
    Mögliche Werte:
    • FEHLER
    • ERFOLG

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie alle verfügbaren Benutzer vom Service Provider für Prüfungstests abgerufen werden, dessen geschäftliche E-Mail-Adresse licius.bagnoli enthält.

    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);

    Antwort:

    //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 (Zeichenfolge provider, Zeichenfolge resourceName, Zeichenfolge providerResourceId, Zuordnung<String, String> queryParams)

    Gibt eine Ressource aus dem externen Anbietersystem mit der angegebenen eindeutigen Ressourcen-ID zurück.

    Diese Informationen werden verwendet, um die entsprechende API des SCIM-Service Providers aufzurufen.

    Tabelle : 5. Parameter
    Name Typ Beschreibung
    Anbieter Zeichenfolge Erforderlich. Name des konfigurierten SCIM-Service Providers Der Name des Service Providers wird im Namensfeld der Tabelle „SCIM-Provider“ [sys_scim_provider] definiert.
    providerResourceId Zeichenfolge Erforderlich. Eindeutiger Bezeichner der zugeordneten Ressource im System des externen Service Providers.
    queryParams Zeichenfolge Erforderlich. SCIM-konforme Abfrageparameter, die an den Endpunkt des externen SCIM-Service Providers übergeben werden.
    Weitere Informationen zu den verfügbaren Abfrageparametern und dem zugehörigen Format finden Sie in den folgenden Abschnitten im Dokument der Internet Engineering Task Force: System für domänenübergreifendes Identitätsmanagement: Protokoll
    Tabelle : 6. Rückgaben
    Typ Beschreibung
    Nachricht Wenn status ERFOLGREICH ist, gibt der Endpunkt den Antworttext gemäß der REST- SCIM- API zurück.

    Datentyp: Zeichenfolge
    status Status der Anforderung.
    Mögliche Werte:
    • FEHLER
    • ERFOLG

    Datentyp: Zeichenfolge

    In diesem Beispiel wird gezeigt, wie die angegebene Ressource aus dem externen Anbietersystem „snow test“ abgerufen wird.

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

    Ausgabe:

    // 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 – Bereitstellung (Zeichenfolge Provider, Zeichenfolge resourceName, Zeichenfolge resourceId)

    Erstellt oder aktualisiert eine Ressource in einem externen Service Provider-System für eine angegebene sys_id.

    Wenn Sie beispielsweise einen Benutzer in einer Instanz ServiceNow erstellen oder aktualisieren, können Sie mit dieser Methode dieselbe Ressource in einem externen Service Provider-System erstellen oder aktualisieren. Nur die Felder, die in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping ] zugeordnet sind, können in der entsprechenden Ressource erstellt oder aktualisiert werden.

    Weitere Informationen zur Zuordnung von Anbieterressourcen finden Sie unter Ressourcenzuordnung für SCIM-Anbieter erstellen.

    Tabelle : 7. Parameter
    Name Typ Beschreibung
    Anbieter Zeichenfolge Erforderlich. Name des konfigurierten SCIM-Service Providers Der Name des Service Providers wird im Namensfeld der Tabelle „SCIM-Provider“ [sys_scim_provider] definiert.
    resourceName Zeichenfolge Erforderlich. Name des Ressourcentyps, z. B. Benutzer oder Gruppe.

    Tabelle: Im Feld resource_name der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    resourceId Zeichenfolge Erforderlich. Sys_id der in der Instanz ServiceNow (dem Client) gespeicherten Ressource.

    Tabelle: Im Feld primary_table der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    Tabelle : 8. Rückgaben
    Typ Beschreibung
    Nachricht Wenn status ERFOLGREICH ist, gibt der Endpunkt den Antworttext gemäß der REST- SCIM- API zurück.

    Datentyp: Zeichenfolge
    status Status der Anforderung.
    Mögliche Werte:
    • FEHLER
    • ERFOLG

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie ein Benutzer im Snow Provider bereitgestellt wird.

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

    Ausgabe:

    // 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 (Zeichenfolge Provider, Zeichenfolge resourceName, Zeichenfolge resourceId)

    Erstellt eine neue Ressource in einem externen Service Provider-System für eine angegebene sys_id.

    Wenn Sie beispielsweise einen neuen Benutzer in einer Instanz ServiceNow erstellen, können Sie mit dieser Methode dieselbe Ressource im System eines externen Service Providers erstellen. Nur die Felder, die in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping] zugeordnet sind, können im entsprechenden System des externen Service Providers erstellt werden. Wenn die Ressource bereits im System des externen Service Providers vorhanden ist, wird eine Fehlerantwort zurückgegeben.

    Weitere Informationen zur Zuordnung von Anbieterressourcen finden Sie unter Ressourcenzuordnung für SCIM-Anbieter erstellen.

    Tabelle : 9. Parameter
    Name Typ Beschreibung
    Anbieter Zeichenfolge Erforderlich. Name des konfigurierten SCIM-Service Providers Der Name des Service Providers wird im Namensfeld der Tabelle „SCIM-Provider“ [sys_scim_provider] definiert.
    resourceName Zeichenfolge Erforderlich. Name des Ressourcentyps, z. B. Benutzer oder Gruppe.

    Tabelle: Im Feld resource_name der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    resourceId Zeichenfolge Erforderlich. Sys_id der in der Instanz ServiceNow (dem Client) gespeicherten Ressource.

    Tabelle: Im Feld primary_table der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping]
    Tabelle : 10. Rückgaben
    Typ Beschreibung
    Nachricht Wenn status ERFOLGREICH ist, gibt der Endpunkt den Antworttext gemäß der REST- SCIM- API zurück.

    Datentyp: Zeichenfolge
    status Status der Anforderung.
    Mögliche Werte:
    • FEHLER
    • ERFOLG

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Sie einen neuen Anwender im externen Service Provider SNOW Provider erstellen.

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

    Ausgabe:

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