このページは Cloud Translation API によって翻訳されました。

外部 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 マッピングを設定する前に、ID プロバイダを Google Cloud プロジェクトに接続します。

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 マッピングストアを削除する