SCIM2Client – Scoped

Die SCIM2Client -API ruft den System for Cross-Domain Identity Management (SCIM) Provider (Serverrolle) auf, um Daten in einem Service Provider (SP) zu erstellen, zu aktualisieren oder zu löschen.

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

Die folgende Abbildung zeigt typische API-Aufruf-Flows zum Bearbeiten von Service Provider-Daten.

Diese API wird im sn_auth- Namespace 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 finden die Ergebnisse jedes SCIM-Methodenaufrufs in der Tabelle „SCIM-Client-Protokolle“ [sys_scim_client_logs].

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

SCIM2Client – executeDelete (String provider, String resourceName, String providerResourceId)

Löscht eine angegebene Ressource aus einem externen Service Provider-System.

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. Dieser Wert befindet sich im Feld resource_name in 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. Ergebnisse

Typ	Beschreibung
Nachricht	Wenn status ERFOLG ist, gibt der Endpunkt den Antworttext zurück, wie durch die REST -SCIM- API definiert. Datentyp: Zeichenfolge
status	Status der Anforderung. Mögliche Werte: FEHLER ERFOLG Datentyp: Zeichenfolge

Das folgende Beispiel zeigt, wie eine Benutzerressource im SNOW Provider-System 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 (String provider, String resourceName, String queryParams)

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

Diese Informationen werden verwendet, um die entsprechende SCIM-Service Provider-API 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. Dieser Wert befindet sich im Feld resource_name in 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 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.3 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5

Tabelle : 4. Ergebnisse

Typ	Beschreibung
Nachricht	Wenn status ERFOLG ist, gibt der Endpunkt den Antworttext zurück, wie durch die REST -SCIM- API definiert. Datentyp: Zeichenfolge
status	Status der Anforderung. Mögliche Werte: FEHLER ERFOLG Datentyp: Zeichenfolge

Das folgende Beispiel zeigt, wie alle verfügbaren Benutzer des Testservice-Providers „snow“ abgerufen werden, deren geschäftliche E-Mail-Adresse Lucius.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\":\"[e-mail]\",
        \"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\":\"[e-mail]\",
        \"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 (String provider, String resourceName, String providerResourceId, Map<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 SCIM-Service Provider-API 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 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.3 https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.5

Tabelle : 6. Ergebnisse

Typ	Beschreibung
Nachricht	Wenn status ERFOLG ist, gibt der Endpunkt den Antworttext zurück, wie durch die REST -SCIM- API definiert. Datentyp: Zeichenfolge
status	Status der Anforderung. Mögliche Werte: FEHLER ERFOLG Datentyp: Zeichenfolge

Dieses Beispiel zeigt, wie die angegebene Ressource vom 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\":\"[e-mail]\",
        \"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 – provision (String provider, String resourceName, String 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 ServiceNow -Instanz erstellen oder aktualisieren, können Sie diese Methode verwenden, um dieselbe Ressource in einem externen Service Provider-System zu erstellen oder zu 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 Provider-Ressourcen finden Sie unter SCIM-Provider-Ressourcenzuordnung 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. Dieser Wert befindet sich im Feld resource_name in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping].
resourceId	Zeichenfolge	Erforderlich. Sys_id der Ressource, die in der Instanz ServiceNow (dem Client) gespeichert ist. Dieser Wert befindet sich im Feld primary_table in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping].

Tabelle : 8. Ergebnisse

Typ	Beschreibung
Nachricht	Wenn status ERFOLG ist, gibt der Endpunkt den Antworttext zurück, wie durch die REST -SCIM- API definiert. Datentyp: Zeichenfolge
status	Status der Anforderung. Mögliche Werte: FEHLER ERFOLG Datentyp: Zeichenfolge

Das folgende Beispiel zeigt, wie ein Benutzer für den Anbieter „Snow“ 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\":\"[e-mail]\",
        \"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 (String provider, String resourceName, String 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 ServiceNow -Instanz erstellen, können Sie diese Methode verwenden, um dieselbe Ressource in einem externen Service Provider-System zu erstellen. Nur die Felder, die in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping] zugeordnet sind, können im entsprechenden externen Service Provider-System erstellt werden. Wenn die Ressource bereits im System des externen Service Providers vorhanden ist, wird eine Fehlerantwort zurückgegeben.

Weitere Informationen zur Zuordnung von Provider-Ressourcen finden Sie unter SCIM-Provider-Ressourcenzuordnung 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. Dieser Wert befindet sich im Feld resource_name in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping].
resourceId	Zeichenfolge	Erforderlich. Sys_id der Ressource, die in der Instanz ServiceNow (dem Client) gespeichert ist. Dieser Wert befindet sich im Feld primary_table in der Tabelle „SCIM-Provider-Ressourcenzuordnung“ [sys_scim_provider_resource_mapping].

Tabelle : 10. Ergebnisse

Typ	Beschreibung
Nachricht	Wenn status ERFOLG ist, gibt der Endpunkt den Antworttext zurück, wie durch die REST -SCIM- API definiert. Datentyp: Zeichenfolge
status	Status der Anforderung. Mögliche Werte: FEHLER ERFOLG Datentyp: Zeichenfolge

Das folgende Beispiel zeigt, wie ein neuer Benutzer beim externen Service Provider SNOW Provider erstellt wird.

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\":\"[e-mail]\",
        \"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"
}