SCIM2Client - スコープ指定

Yokohama API リファレンス

Release

yokohama

ft:locale

ja-JP

ft:publication_title

Yokohama API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

SCIM2Client - スコープ指定

リリースバージョン: Yokohama

更新日 2025年01月30日

所要時間：27分

SCIM2Client API は、クロスドメイン ID 管理システム (SCIM) プロバイダー (サーバーロール) を呼び出して、サービスプロバイダー (SP) のデータを作成、更新、または削除するメソッドを提供します。

SCIM は、クライアントとサーバーのロールを定義する REST および JSON ベースのプロトコルです。クライアントは通常、ユーザー ID の堅牢なディレクトリを含む Okta ID プロバイダー (IDP) です。SP は通常、Box や Slack などの SaaS アプリケーションであり、これらの ID からの情報のサブセットを必要とします。IDP で ID が変更 (作成、更新、削除など) されると、変更は SCIM プロトコルに従って自動的に SP に同期されます。

次の画像は、サービスプロバイダーのデータを操作するための一般的な API コールフローを示しています。

SCMI Client API のコールフロー

この API は sn_auth 名前空間で実行されます。API にアクセスするには、SCIM v2 - ServiceNow Cross-domain Identity Management Client (com.snc.integration.scim2.client) プラグインがインストールされている必要があります。

それぞれの SCIM メソッドの呼び出しの結果は、SCIM クライアントログ [sys_scim_client_logs] テーブルで確認できます。

SCIM の詳細については、「クロスドメイン ID 管理システム (SCIM)」を参照してください。

SCIM2Client - executeDelete(文字列 provider, 文字列 resourceName, 文字列 providerResourceId)

指定されたリソースを外部サービスプロバイダーシステムから削除します。

表 : 1. パラメーター
名前	タイプ	説明
provider	文字列	必須です。設定された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
resourceName	文字列	必須です。ユーザーやグループなどのリソースタイプの名前。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
providerResourceId	文字列	必須です。外部サービスプロバイダーシステム上の関連付けられたリソースの一意の識別子。

表 : 2. 返される内容
タイプ	説明
message	status が SUCCESS の場合、エンドポイントは、REST SCIM API で定義された応答本文を返します。データタイプ：文字列
status	要求のステータス可能な値： FAILURE SUCCESS データタイプ：文字列

次の例は、SNOW プロバイダーシステムでユーザーリソースを削除する方法を示しています。

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

出力：

// 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(文字列 provider, 文字列 resourceName, 文字列 queryParams)

指定された外部プロバイダーシステムから取得された、渡された基準に一致するすべてのリソースを返します。

この情報は、対応する SCIM サービスプロバイダーの API を呼び出すために使用されます。

表 : 3. パラメーター
名前	タイプ	説明
provider	文字列	必須です。設定された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
resourceName	文字列	必須です。ユーザーやグループなどのリソースタイプの名前。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
queryParams	文字列	必須です。外部 SCIM サービスプロバイダーのエンドポイントに渡される SCIM 準拠のクエリパラメーター。使用可能なクエリパラメーターとその関連形式の詳細については、インターネットエンジニアリングタスクフォースのドキュメント「System for Cross-domain Identity Management: Protocol」を参照してください。 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

表 : 4. 返される内容
タイプ	説明
message	status が SUCCESS の場合、エンドポイントは、REST SCIM API で定義された応答本文を返します。データタイプ：文字列
status	要求のステータス可能な値： FAILURE SUCCESS データタイプ：文字列

次の例は、仕事用のメールに「lucius.bagnoli」が含まれている利用可能なすべてのユーザーを、snow test というサービスプロバイダーから取得する方法を示しています。

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

応答：

//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(文字列 provider, 文字列 resourceName, 文字列 providerResourceId, マップ<文字列, 文字列> queryParams)

指定された一意のリソース ID を持つリソースを外部プロバイダーシステムから返します。

この情報は、対応する SCIM サービスプロバイダーの API を呼び出すために使用されます。

表 : 5. パラメーター
名前	タイプ	説明
provider	文字列	必須です。設定された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
providerResourceId	文字列	必須です。外部サービスプロバイダーシステム上の関連付けられたリソースの一意の識別子。
queryParams	文字列	必須です。外部 SCIM サービスプロバイダーのエンドポイントに渡される SCIM 準拠のクエリパラメーター。使用可能なクエリパラメーターとその関連形式の詳細については、インターネットエンジニアリングタスクフォースのドキュメント「System for Cross-domain Identity Management: Protocol」を参照してください。 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

表 : 6. 返される内容
タイプ	説明
message	status が SUCCESS の場合、エンドポイントは、REST SCIM API で定義された応答本文を返します。データタイプ：文字列
status	要求のステータス可能な値： FAILURE SUCCESS データタイプ：文字列

この例では、「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);

出力：

// 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 - provision(文字列 provider, 文字列 resourceName, 文字列 resourceId)

外部サービスプロバイダーシステムで、指定された sys_id のリソースを作成または更新します。

たとえば、ServiceNow インスタンスでユーザーを作成または更新する場合、このメソッドを使用すれば外部サービスプロバイダーシステムで同じリソースを作成または更新できます。対応するリソースで作成または更新できるのは、SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルにマッピングされているフィールドのみです。

プロバイダーリソースマッピングの詳細については、「 SCIM プロバイダーリソースマッピングの作成」を参照してください。

表 : 7. パラメーター
名前	タイプ	説明
provider	文字列	必須です。設定された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
resourceName	文字列	必須です。ユーザーやグループなどのリソースタイプの名前。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
resourceId	文字列	必須です。ServiceNow インスタンス (クライアント) に保存されているリソースの sys_id。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [primary_table] フィールド。

表 : 8. 返される内容
タイプ	説明
message	status が SUCCESS の場合、エンドポイントは、REST SCIM API で定義された応答本文を返します。データタイプ：文字列
status	要求のステータス可能な値： FAILURE SUCCESS データタイプ：文字列

次の例は、Snow Provider でユーザーをプロビジョニングする方法を示しています。

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

出力：

// 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(文字列 provider, 文字列 resourceName, 文字列 resourceId)

外部サービスプロバイダーシステムで、指定された sys_id のリソースを新規作成します。

たとえば、ServiceNow インスタンスでユーザーを新規作成する場合、このメソッドを使用すれば外部サービスプロバイダーシステムで同じリソースを作成できます。対応する外部サービスプロバイダーシステムで作成できるのは、SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルにマッピングされているフィールドのみです。リソースが外部サービスプロバイダーシステムにすでに存在する場合は、エラー応答が返されます。

プロバイダーリソースマッピングの詳細については、「 SCIM プロバイダーリソースマッピングの作成」を参照してください。

表 : 9. パラメーター
名前	タイプ	説明
provider	文字列	必須です。設定された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
resourceName	文字列	必須です。ユーザーやグループなどのリソースタイプの名前。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
resourceId	文字列	必須です。ServiceNow インスタンス (クライアント) に保存されているリソースの sys_id。テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [primary_table] フィールド。

表 : 10. 返される内容
タイプ	説明
message	status が SUCCESS の場合、エンドポイントは、REST SCIM API で定義された応答本文を返します。データタイプ：文字列
status	要求のステータス可能な値： FAILURE SUCCESS データタイプ：文字列

次の例は、SNOW Provider という外部サービスプロバイダーでユーザーを新規作成する方法を示しています。

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

出力：

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