外部 ID をマッピングする

通常、企業は ID プロバイダ（IDP）を使用して ID（ユーザーとユーザーグループ）を管理します。ただし、企業が社内で構築したカスタムアプリケーションでは、顧客がそのアプリケーション内でローカルに定義された新しいユーザーグループを作成できる場合があります。このようなアプリケーション固有のユーザーグループやセカンダリユーザー ID は、外部 ID と呼ばれます。

ID マッピングを設定する理由

Google がアクセス制御を正しく適用できるようにするには、IDP ID を、Gemini Enterprise で使用する予定のカスタムアプリケーションから取得した外部 ID にマッピングします。

アプリの結果にアクセス制御を適用するために、Google は IDP を信頼できる情報源として使用し、ユーザーがアクセスできるデータを決定します。企業は、従業員が 1 つの企業認証情報を使用してすべての企業リソースにログインしてアクセスできるように、IDP を他の SaaS ソリューションに接続することがよくあります。

カスタムアプリケーションなど、アプリに接続する予定のアプリケーションを通じて外部 ID が定義されている場合、IDP はアクセス制御の唯一の信頼できる情報源ではありません。

たとえば、Example Organization 内に「JaneDoe」というユーザーが存在し、ドメインが「example.com」であるとします。IDP の ID は「JaneDoe@example.com」として定義されます。同じユーザーがカスタムアプリケーション内で「JDoe」という別の ID を持っています。この場合、IDP はこの ID を認識していない可能性があります。そのため、Gemini Enterprise は IDP を介してカスタムアプリケーション ID に関する情報を受け取りません。

Gemini Enterprise では、ID マッピングはマッピングを作成してインポートする ID マッピングストアに保存されます。カスタムコネクタを使用する場合は、ID マッピングストアをカスタムコネクタのデータストアにバインドし、外部 ID に関する情報でデータストアの ACL メタデータを更新できます。

始める前に

ID マッピングを設定する前に、 Google Cloud プロジェクトに ID プロバイダを接続します。

ID マッピングエントリを準備する

インポートする ID マッピングエントリを準備します。ID マッピングは、次の例のようにフォーマットする必要があります。

{
  "identity_mapping_entries": [
    {
      "external_identity": "u1",
      "user_id": "user1@example.com"
    },
    {
      "external_identity": "u2",
      "user_id": "user2@example.com"
    },
    {
      "external_identity": "gABC",
      "group_id": "groupABC@example.com"
    }
  ]
}

たとえば、次のグラフはユーザーグループのメンバーシップの例を表しています。ここで、Ext は外部グループを表します。このグラフは、外部グループと IDP ユーザーおよびグループの関係の例を示しています。

IDP ユーザーとグループに対する外部 ID の関係。

このユーザーグループメンバーシップのグラフには、次のマッピングが含まれます。

{
  "identity_mapping_entries": [
    {
      "external_identity": "Ext1",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup1@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup2@example.com"
    }
  ]
}

外部 ID に子 ID があるネストされた ID メンバーシップは、フラット化する必要があります。

Google はコネクタが外部 ID のプライマリ ID を送信することを前提としています。たとえば、名前はカスタムアプリケーション内のグループの存続期間中に変更される可能性があるため、グループ名ではなくグループ ID をインポートします。

ID マッピングを設定する

次の手順に沿って、Gemini Enterprise で IDP と外部 ID 間の ID マッピングを設定します。次の手順では、ID マッピングストアを作成し、準備した ID マッピングをインポートします。カスタムコネクタを使用する場合は、ID マッピングストアにバインドされた新しいデータストアも作成します。

ID マッピングストアを作成する

最初のステップは、ID マッピングストアを設定することです。これは、すべての ID マッピングが保存される親リソースです。

ID マッピングストアを作成すると、Gemini Enterprise プロジェクトに接続した IDP から IDP 構成が自動的に取得されます。

ID マッピングストアを作成するには、identityMappingStores.create メソッドを使用して次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \
-d '{
  "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
}'

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。例: test-id-mapping-store。

コマンドの例と結果

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores?identityMappingStoreId=test-id-mapping-store" \
-d '{
  "name": "projects/example-project/locations/global/identityMappingStores/test-id-mapping-store"
}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

ID マッピングをインポートする

ID マッピングストアを作成したら、準備した ID マッピングエントリをインポートします。

ID マッピングをインポートするには、importIdentityMappings メソッドを使用して次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。
IDENTITY_MAPPINGS_JSON: JSON 形式の準備済みの ID マッピング。

コマンドの例と結果

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:importIdentityMappings" \
-d '{"inline_source" : { identity_mapping_entries: { external_identity: "external_id_1", user_id: "testuser1@example.com" } , identity_mapping_entries: { external_identity: "external_id_2", user_id: "testuser2@example.com" }, identity_mapping_entries: { external_identity: "external_id2", group_id: "testgroup1@example.com" } }}'

{
  "name": "projects/862721868538/locations/global/identityMappingStores/test-id-mapping-store/operations/import-identity-mappings-14869487418543288420",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata",
    "successCount": "2",
    "failureCount": "1",
    "totalCount": "3"
  },
  "done": true
}

次に、カスタムコネクタを構築して外部 ID を使用する場合は、カスタムデータストアを ID マッピングストアにバインドするに進みます。それ以外の場合は、ACL メタデータを更新するに進みます。

カスタムデータストアを ID マッピングストアにバインドする

この手順は、カスタムコネクタを構築する場合にのみ必要です。カスタムコネクタを構築しない場合は、この手順をスキップします。

カスタムコネクタの場合、外部 ID をドキュメントに関連付ける前に、ID マッピングストアをデータストアにバインドする必要があります。このフィールドの設定は、データストアの作成時にのみ許可されます。

データストアを ID マッピングストアにバインドするには、Datastores.create メソッドを使用してデータストアの作成時に identity_mapping_store を指定します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \
-d '{
    ...
    "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME"
}'
```
次のように置き換えます。
- PROJECT_ID: 実際のプロジェクトの ID。
- DATA_STORE_ID: 作成するデータストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
- IDENTITY_MAPPING_STORE_NAME: ID マッピングストアの完全なリソース名。例: projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store。データストアの作成後にこの名前を更新することはできません。

ACL メタデータを追加する

ドキュメントの AclInfo オブジェクトに ACL メタデータを含めます。

ユーザーが検索リクエストを送信し、ACL メタデータに外部 ID が含まれるドキュメントが取得されると、それらの外部 ID が評価されます。ユーザーの ID（groupID または userID）がドキュメントに関連付けられている外部 ID（externalEntityId）にマッピングされている場合、ユーザーはそのドキュメントにアクセスできます。

たとえば、Jira 用のカスタムコネクタを作成したとします。特定の Jira の課題には、特定の IDP ユーザー、特定の IDP グループ、管理者ロールがアクセスできます。検索結果でその課題にアクセスできるようにするには、ID マッピングストアを作成し、IDP ユーザーとグループを Jira 固有の外部 ID にマッピングします。ID マッピングストアを Jira データストアにバインドします。次に、これらのドキュメントにアクセスできる IDP ユーザー、IDP グループ、外部 ID で構成された aclInfo を使用して、Jira データストアにドキュメントを作成します。

外部 ID に関する情報で ACL メタデータを更新するには、次の形式を使用して外部 ID と関連するユーザー ID およびグループ ID を指定します。

{
  "aclInfo": {
    "readers": [
      {
        "principals": [
          {
            "groupId": "group_1"
          },
          {
            "userId": "user_1"
          },
          {
            "externalEntityId": "external_id1"
          }

        ]
      }
    ]
  }
}

ACL メタデータの更新について詳しくは、アクセス制御でデータソースを構成するをご覧ください。

ID マッピングを管理する

ID ストア内の ID マッピングを一覧表示できます。また、インラインソースで定義するかフィルタ条件を使用して定義することで、ID ストアを削除することもできます。

ID マッピングで使用できる管理タスクは次のとおりです。

ID マッピングを一覧表示する
インラインソースを使用して削除する
フィルタ条件を使用して削除する

ID マッピングを一覧表示する

ID マッピングを一覧表示するには、listIdentityMappings メソッドを使用して次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
PAGE_SIZE: 返される ID マッピングストアの最大数。指定されていない場合のデフォルトは 100 です。最大許容値は 1,000 です。1,000 を超える値は 1,000 に強制変換されます。
PAGE_TOKEN: 前回の ListIdentityMappingStores 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

コマンドの例と結果

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: example-project" \
https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:listIdentityMappings

{
  "identityMappingEntries": [
    {
      "externalIdentity": "external_group2",
      "groupId": "example-group@google.com"
    },
    {
      "externalIdentity": "external_id_1",
      "userId": "example-user@google.com"
    }
  ],
  "nextPageToken": "gNiNWOiRTMxEWMwATLmNDMh1CO0IjMtADMwATLkRWYkZTZ3YDJawB2h-LEG8ro3XLCLIBZ2YmNz"
}

インラインソースを使用して削除する

削除する ID の JSON ファイルを指定することで、ID マッピングストアから特定のエントリを削除できます。

インラインソースを使用して ID マッピングを削除するには、purgeIdentityMappings メソッドを使用して次のコマンドを実行します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'
```
次のように置き換えます。
- PROJECT_ID: 実際のプロジェクトの ID。
- IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。
- IDENTITY_MAPPING_STORE_NAME: ID マッピングストアの名前。
- IDENTITY_MAPPINGS_JSON: 削除する ID マッピング。

フィルタ条件を使用して削除する

更新時間、外部 ID、またはすべてのエントリでエントリをフィルタして、ID マッピングストアから特定のエントリを削除できます。

フィルタ条件を使用して ID マッピングを削除するには、purgeIdentityMappings メソッドを使用して次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。
IDENTITY_MAPPING_STORE_NAME: ID マッピングストアの名前。
FILTER_CONDITION: 次のいずれかのフィルタタイプ。

更新日時。例: update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">
外部 ID。例: external_id = "id1"
すべての ID マッピング。例: *

コマンドの例と結果

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/ucs-ga-fishfood-1/locations/global/identityMappingStores/test-id-mapping-store:purgeIdentityMappings" \
-d '{"identity_mapping_store":"test-id-mapping-store", "filter": "*"}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store/operations/purge-identity-mappings-200445172458892000",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata"
  }
}

ID マッピングストアを管理する

ID マッピングストアの取得、削除、一覧表示、完全な削除を行うことができます。

ID マッピングストアを取得する

ID マッピングストアを取得するには、identityMappingStores.get メソッドを使用して次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。
IDENTITY_MAPPING_STORE_NAME: ID マッピングストアの名前。

コマンドの例と結果

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store"

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

ID マッピングストアを一覧表示する

ID マッピングストアを一覧表示するには、identityMappingStores.list メソッドを使用して次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
PAGE_SIZE: 返される ID マッピングストアの最大数。指定されていない場合のデフォルトは 100 です。最大許容値は 1,000 です。1,000 を超える値は 1,000 に強制変換されます。
PAGE_TOKEN: 前回の ListIdentityMappingStores 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

コマンドの例と結果

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores"

{
  "identityMappingStores": [
    {
      "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
      "idpConfig": {
        "idpType": "GSUITE"
      }
    }
  ]
}

ID マッピングストアを削除する

ID マッピングストアを削除するには、そのストアがデータストアにバインドされておらず、ID マッピングストアに ID マッピングが存在していない必要があります。

ID マッピングストアを削除するには、identityMappingStores.delete メソッドを使用して次のコマンドを実行します。
```
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
```
次のように置き換えます。
- PROJECT_ID: 実際のプロジェクトの ID。
- IDENTITY_MAPPING_STORE_ID: ID マッピングストアの一意の ID。
- IDENTITY_MAPPING_STORE_NAME: ID マッピングストアの名前。

外部 ID をマッピングする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ID マッピングを設定する理由

始める前に

ID マッピング エントリを準備する

ID マッピングを設定する

ID マッピング ストアを作成する

コマンドの例と結果

ID マッピングをインポートする

コマンドの例と結果

カスタム データストアを ID マッピング ストアにバインドする

ACL メタデータを追加する

ID マッピングを管理する

ID マッピングを一覧表示する

コマンドの例と結果

インライン ソースを使用して削除する

フィルタ条件を使用して削除する

コマンドの例と結果

ID マッピング ストアを管理する

ID マッピング ストアを取得する

コマンドの例と結果

ID マッピング ストアを一覧表示する

コマンドの例と結果

ID マッピング ストアを削除する

外部 ID をマッピングする

ID マッピングエントリを準備する

ID マッピングストアを作成する

カスタムデータストアを ID マッピングストアにバインドする

インラインソースを使用して削除する

ID マッピングストアを管理する

ID マッピングストアを取得する

ID マッピングストアを一覧表示する

ID マッピングストアを削除する