SCIM2Client - スコープ指定

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：27分

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

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

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

    SCMI クライアント API 呼び出しフロー

    この API は sn_auth 名前空間で実行され、API にアクセスするには SCIM v2 - ServiceNow クロスドメイン ID 管理クライアント (com.snc.integration.scim2.client) プラグインをインストールする必要があります。

    各 SCIM メソッド呼び出しの結果は、SCIM クライアントログ [sys_scim_client_logs] テーブルにあります。

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

    SCIM2Client - executeDelete (文字列プロバイダー、文字列 resourceName、文字列 providerResourceId)

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

    表 : 1. パラメーター
    名前 タイプ 説明
    プロバイダー 文字列 必須。構成された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
    resourceName 文字列 必須。ユーザーやグループなどのリソースタイプの名前。

    テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
    providerResourceId 文字列 必須。外部サービスプロバイダーシステム上の関連リソースの一意の識別子。
    表 : 2. 戻り値
    タイプ 説明
    メッセージ statusが「成功」の場合、エンドポイントは REST SCIM API で定義された応答本文を返します。

    データタイプ：文字列
    ステータス 要求のステータス。
    可能な値：
    • 失敗
    • 成功

    データタイプ：文字列

    次の例は、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 (文字列プロバイダー、文字列 resourceName、文字列 queryParams)

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

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

    表 : 3. パラメーター
    名前 タイプ 説明
    プロバイダー 文字列 必須。構成された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
    resourceName 文字列 必須。ユーザーやグループなどのリソースタイプの名前。

    テーブル:SCIM プロバイダーリソースマッピング [sys_scim_provider_resource_mapping] テーブルの [resource_name] フィールド。
    queryParams 文字列 必須。外部 SCIM サービスプロバイダーエンドポイントに渡される SCIM 準拠のクエリパラメーター。
    使用可能なクエリーパラメーターとそれに関連する形式の詳細については、インターネットエンジニアリングタスクフォースのドキュメントの次のセクションを参照してください。 クロスドメイン ID 管理システム:プロトコル
    表 : 4. 戻り値
    タイプ 説明
    メッセージ statusが「成功」の場合、エンドポイントは REST SCIM API で定義された応答本文を返します。

    データタイプ：文字列
    ステータス 要求のステータス。
    可能な値：
    • 失敗
    • 成功

    データタイプ：文字列

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

    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 (文字列プロバイダー、文字列 resourceName、文字列 providerResourceId、 Map<String、文字列> queryParams)

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

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

    表 : 5. パラメーター
    名前 タイプ 説明
    プロバイダー 文字列 必須。構成された SCIM サービスプロバイダーの名前。サービスプロバイダー名は、SCIM プロバイダー [sys_scim_provider] テーブルの名前フィールドで定義されます。
    providerResourceId 文字列 必須。外部サービスプロバイダーシステム上の関連リソースの一意の識別子。
    queryParams 文字列 必須。外部 SCIM サービスプロバイダーエンドポイントに渡される SCIM 準拠のクエリパラメーター。
    使用可能なクエリーパラメーターとそれに関連する形式の詳細については、インターネットエンジニアリングタスクフォースのドキュメントの次のセクションを参照してください。 クロスドメイン ID 管理システム:プロトコル
    表 : 6. 戻り値
    タイプ 説明
    メッセージ statusが「成功」の場合、エンドポイントは REST SCIM API で定義された応答本文を返します。

    データタイプ：文字列
    ステータス 要求のステータス。
    可能な値：
    • 失敗
    • 成功

    データタイプ：文字列

    この例では、外部プロバイダーシステムの「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 - プロビジョニング (文字列プロバイダー、文字列 resourceName、文字列 resourceId)

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

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

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

    表 : 7. パラメーター
    名前 タイプ 説明
    プロバイダー 文字列 必須。構成された 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. 戻り値
    タイプ 説明
    メッセージ statusが「成功」の場合、エンドポイントは REST SCIM API で定義された応答本文を返します。

    データタイプ：文字列
    ステータス 要求のステータス。
    可能な値：
    • 失敗
    • 成功

    データタイプ：文字列

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

    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 (文字列プロバイダー、文字列 resourceName、文字列 resourceId)

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

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

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

    表 : 9. パラメーター
    名前 タイプ 説明
    プロバイダー 文字列 必須。構成された 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. 戻り値
    タイプ 説明
    メッセージ statusが「成功」の場合、エンドポイントは REST SCIM API で定義された応答本文を返します。

    データタイプ：文字列
    ステータス 要求のステータス。
    可能な値：
    • 失敗
    • 成功

    データタイプ：文字列

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

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