データソースのアクセス制御を使用する

このページでは、Vertex AI Agent Builder で検索アプリのデータソースのアクセス制御を適用する方法について説明します。

Vertex AI Agent Builder のデータソースのアクセス制御により、検索アプリの結果でユーザーが表示できるデータが制限されます。Google は、ID プロバイダを使用して検索を実行したエンドユーザーを特定し、結果として返されたドキュメントにアクセスできるかどうかを判断します。

たとえば、社員が検索アプリを使用して Confluence ドキュメントを検索するとします。ただし、アクセス権のないコンテンツをアプリで表示できないようにする必要があります。組織の ID プロバイダ用に Google Cloud で Workforce プールを設定している場合は、Vertex AI Agent Builder でその Workforce プールを指定することもできます。これで、社員がアプリを使用すると、そのアカウントが Confluence ですでにアクセス権を持っているドキュメントの検索結果のみが表示されます。

データソースのアクセス制御について

アクセス制御の有効化は 1 回限りの手順です。

アクセス制御は、Cloud Storage、BigQuery、Google ドライブ、およびすべてのサードパーティデータソースで使用できます。

Vertex AI Agent Builder のデータソースアクセス制御を有効にするには、組織の ID プロバイダが Google Cloud で構成されている必要があります。次の認証フレームワークがサポートされています。

Google Identity: Google Identity を使用する場合、すべてのユーザー ID とユーザーグループが存在し、Google Cloud で管理されます。Google Identity の詳細については、Google Identity のドキュメントをご覧ください。
サードパーティの ID プロバイダの連携: Okta や Azure AD などの外部 ID プロバイダを使用する場合は、Vertex AI Agent Builder のデータソースアクセス制御を有効にする前に、Google Cloud でWorkforce Identity 連携を設定する必要があります。

サードパーティのコネクタを使用する場合は、google.subject 属性を外部 ID プロバイダのメールアドレスフィールドにマッピングする必要があります。以下に、よく使用される ID プロバイダの google.subject 属性と google.groups 属性のマッピング例を示します。
- OIDC プロトコルを使用した Azure AD
```
google.subject=assertion.email
google.groups=assertion.groups
```
- SAML プロトコルを使用した Azure AD
```
google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
```
- OIDC プロトコルを使用した Okta
```
google.subject=assertion.email
google.groups=assertion.groups
```
- SAML プロトコルを使用した Okta
```
google.subject=assertion.subject
google.groups=assertion.attributes['groups']
```

制限事項

アクセス制御には次の制限があります。

ドキュメントごとに 250 人の読み取りユーザーを指定できます。各プリンシパルは読み取りユーザーとしてカウントされます。プリンシパルはグループまたは個々のユーザーです。
Vertex AI Search でサポートされているロケーションごとに 1 つの ID プロバイダを選択できます。
アクセス制御は、ID プロバイダで明示的に定義された ID とグループに対してのみ適用されます。サードパーティ製アプリ内でネイティブに定義された ID またはグループはサポートされません。
データソースをアクセス制御付きとして設定するには、データストアの作成時にこの設定を選択する必要があります。既存のデータストアでは、この設定をオンまたはオフにすることはできません。
コンソールの [データ] > [ドキュメント] タブには、アクセス制御付きデータソースのデータは表示されません。このデータは、表示アクセス権を持つユーザーにのみ表示される必要があるためです。
サードパーティのアクセス制御を使用する検索アプリの UI 結果をプレビューするには、連携コンソールにログインするか、ウェブアプリを使用する必要があります。アクセス制御付きアプリの結果をプレビューするをご覧ください。

始める前に

この手順では、Google Cloud プロジェクトに ID プロバイダを設定していることを前提としています。

Google Identity: Google Identity を使用している場合は、ID プロバイダに接続するの手順に進みます。
サードパーティ ID プロバイダ: サードパーティ ID プロバイダの Workforce Identity プールが設定されていることを確認します。Workforce プールを設定するときに、サブジェクトとグループの属性マッピングを指定していることを確認してください。属性マッピングについては、IAM ドキュメントの属性マッピングをご覧ください。Workforce Identity プールの詳細については、IAM ドキュメントの Workforce Identity プールプロバイダを管理するをご覧ください。

ID プロバイダに接続する

Vertex AI Agent Builder の ID プロバイダを指定してデータソースのアクセス制御を有効にするには、次の操作を行います。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
[設定] > [認証] ページに移動します。
更新するロケーションの [ID プロバイダを追加] をクリックします。
[ID プロバイダを追加] ダイアログで ID プロバイダを選択します。サードパーティの ID プロバイダを選択する場合は、データソースに適用される Workforce プールも選択します。
[変更を保存] をクリックします。

アクセス制御付きのデータソースを構成する

データソースにアクセス制御を適用するには、設定するデータソースの種類に応じて次の手順を行います。

サードパーティのデータソース: アプリの作成時に追加の設定は必要ありません。サードパーティのアクセス制御が設定されたアプリの結果をプレビューするに進みます。
Google ドライブ: アプリの作成時に追加の構成は必要ありません。
Cloud Storage の非構造化データ
Cloud Storage の構造化データ
BigQuery の非構造化データ
BigQuery の構造化データ

Cloud Storage の非構造化データ

Cloud Storage の非構造化データ用のデータストアを設定する場合は、ACL メタデータをアップロードし、データストアをアクセス制御付きとして設定する必要があります。

データを準備するときに、acl_info フィールドを使用して ACL 情報をメタデータに含めます。例:

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "content": {
     "mimeType": "<application/pdf or text/html>",
     "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
   },
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

メタデータを含む非構造化データの詳細については、取り込み用にデータを準備するの非構造化データのセクションをご覧ください。

検索データストアを作成するで説明されているデータストアの作成手順を行う際に、コンソールまたは API を使用して次の操作を行うと、アクセス制御を有効にできます。
- コンソール: データストアを作成するときに、データストアの作成時に [このデータストアはアクセス制御情報を含む] を選択します。
- API: データストアを作成するときに、JSON ペイロードにフラグ "aclEnabled": "true" を含めます。
検索データストアを作成するで説明されているデータインポートの手順を行う際に、次の操作を行います。
- 非構造化データと同じバケットから ACL 情報を含むメタデータをアップロードする
- API を使用している場合は、GcsSource.dataSchema を document に設定する

Cloud Storage の構造化データ

Cloud Storage の構造化データ用のデータストアを設定する場合は、ACL メタデータをアップロードし、データストアをアクセス制御付きとして設定する必要があります。

データを準備するときに、acl_info フィールドを使用して ACL 情報をメタデータに含めます。例:

{
   "id": "<your-id>",
   "jsonData": "<JSON string>",
   "acl_info": {
     "readers": [
       {
         "principals": [
           { "group_id": "group_1" },
           { "user_id": "user_1" }
         ]
       }
     ]
   }
 }

検索データストアを作成するで説明されているデータストアの作成手順を行う際に、コンソールまたは API を使用して次の操作を行うと、アクセス制御を有効にできます。
- コンソール: データストアを作成するときに、データストアの作成時に [このデータストアはアクセス制御情報を含む] を選択します。
- API: データストアを作成するときに、JSON ペイロードにフラグ "aclEnabled": "true" を含めます。
検索データストアを作成するで説明されているデータインポートの手順を行う際に、次の操作を行います。
- 非構造化データと同じバケットから ACL 情報を含むメタデータをアップロードする
- API を使用している場合は、GcsSource.dataSchema を document に設定する

BigQuery の非構造化データ

BigQuery の非構造化データ用のデータストアを設定する場合は、データストアをアクセス制御付きとして設定し、Vertex AI Search 用に事前定義されたスキーマを使用して ACL メタデータを指定する必要があります。

データを準備するときに、次のスキーマを指定します。カスタムスキーマは使用しないでください。

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "content",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "mimeType",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

ACL メタデータを BigQuery テーブルの列として含めます。
検索データストアを作成するの手順を行う際に、コンソールまたは API を使用してアクセス制御を有効にします。
- コンソール: データストアを作成するときに、データストアの作成時に [このデータストアはアクセス制御情報を含む] を選択します。
- API: データストアを作成するときに、JSON ペイロードにフラグ "aclEnabled": "true" を含めます。
検索データストアを作成するで説明されているデータインポートの手順を行う際に、API を使用する場合は、BigQuerySource.dataSchema を document に設定します。

BigQuery の構造化データ

BigQuery の構造化データ用のデータストアを設定する場合は、データストアをアクセス制御付きとして設定し、Vertex AI Search 用に事前定義されたスキーマを使用して ACL メタデータを指定する必要があります。

データを準備するときに、次のスキーマを指定します。カスタムスキーマは使用しないでください。

[
  {
    "name": "id",
    "mode": "REQUIRED",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "jsonData",
    "mode": "NULLABLE",
    "type": "STRING",
    "fields": []
  },
  {
    "name": "acl_info",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "readers",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
          {
            "name": "principals",
            "type": "RECORD",
            "mode": "REPEATED",
            "fields": [
              {
                "name": "user_id",
                "type": "STRING",
                "mode": "NULLABLE"
              },
              {
                "name": "group_id",
                "type": "STRING",
                "mode": "NULLABLE"
              }
            ]
          }
        ]
      }
    ]
  }
]

ACL メタデータを BigQuery テーブルの列として含めます。
検索データストアを作成するの手順を行う際に、コンソールまたは API を使用してアクセス制御を有効にします。
- コンソール: データストアを作成するときに、データストアの作成時に [このデータストアはアクセス制御情報を含む] を選択します。
- API: データストアを作成するときに、JSON ペイロードにフラグ "aclEnabled": "true" を含めます。
検索データストアを作成するで説明されているデータインポートの手順を行う際に、次の操作を行います。
- コンソールを使用している場合は、アップロードするデータの種類を指定するときに、[メタデータを含む構造化データの JSONL] を選択する
- API を使用している場合は、BigQuerySource.dataSchema を document に設定する

サードパーティのアクセス制御が設定されたアプリの結果をプレビューする

サードパーティのアクセス制御が設定されたアプリの結果をコンソールでプレビューするには、組織の認証情報でログインする必要があります。

UI の結果をプレビューするには、次の 2 つの方法があります。

Workforce Identity 連携コンソール。Workforce Identity 連携コンソールを開き、サードパーティの認証情報でログインします。Workforce Identity 連携コンソールで結果をプレビューするをご覧ください。
ウェブアプリ。 Vertex AI Search が提供する専用のウェブアプリを有効にしてログインします。ウェブアプリを有効にするをご覧ください。

Workforce Identity 連携コンソールで結果をプレビューする

Workforce Identity 連携コンソールを使用して結果を表示する手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
結果をプレビューする検索アプリの名前をクリックします。
[プレビュー] ページに移動します
[連携 ID でプレビュー] をクリックして、Workforce Identity 連携コンソールに移動します。
Workforce プールプロバイダと組織の認証情報を入力します。
表示された [プレビュー] ページで、アプリの結果をプレビューします。

検索結果のプレビューについて詳しくは、検索結果を取得するをご覧ください。

Workforce Identity 連携コンソールの詳細については、コンソール（連携）についてをご覧ください。

ユーザーに検索権限を付与する

ユーザーがアプリを使用してアクセス制御付きのデータを検索できるようにするには、ドメインまたは Workforce プール内のユーザーにアクセス権を付与する必要があります。ユーザーグループにカスタム IAM ロールを付与することをおすすめします。

Google Identity: Google Identity を使用している場合は、検索が必要なすべての社員を含む Google グループを作成することをおすすめします。Google Workspace 管理者の場合は、組織のすべてのユーザーをグループに追加するの手順に沿って、組織内のすべてのユーザーを Google グループに含めることができます。
サードパーティの ID プロバイダ: Okta や Azure AD などの外部 ID プロバイダを使用している場合は、Workforce プール内のすべてのユーザーを 1 つのグループに追加します。

次の権限を使用して、ユーザーグループに付与するカスタム IAM ロールを作成することをおすすめします。

discoveryengine.answers.get
discoveryengine.servingConfigs.answer
discoveryengine.servingConfigs.search
discoveryengine.sessions.get

Identity and Access Management（IAM）を使用する Vertex AI Agent Builder リソースの権限の詳細については、IAM を使用したアクセス制御をご覧ください。

カスタムロールの詳細については、IAM ドキュメントのカスタムロールをご覧ください。

アクセス制御付きアプリの検索ウィジェットをデプロイする手順は次のとおりです。

検索 API 呼び出しを行う必要があるドメインまたは Workforce プールのユーザーに Discovery Engine 閲覧者のロールを付与します。
ウィジェットに渡す認証トークンを生成します。
- Google Identity の場合: OAuth 2.0 アクセストークンを生成します。
- Workforce Identity 連携の場合: Workforce Identity 連携の有効期間が短いトークンを取得するの手順に沿ってトークンを取得します。
認証トークンを使用してウィジェットを追加するの手順に沿って、トークンをウィジェットに渡します。

ウェブアプリをオンにする

ウェブアプリは、Vertex AI Search によって生成された専用のサイトです。このサイトでは、ログイン認証情報を持つユーザーであれば誰でも検索アプリを使用できます。

検索ウィジェットや検索 API を独自のアプリに統合することなくユーザーに検索アプリを提供するには、ウェブアプリの URL をユーザーに提供します。

ウェブアプリを有効にする手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
ウェブアプリを作成する検索アプリの名前をクリックします。
[統合] > [UI] タブに移動します。
[ウェブアプリを有効にする] をクリックします。
Workforce Identity 連携を使用している場合は、Workforce プールプロバイダを選択します。
ウェブアプリへのリンクをクリックします。
Workforce プールプロバイダと組織の認証情報を入力します。
アプリの結果をプレビューします。
ウェブアプリの結果を構成するには、検索ウィジェットの結果を構成するをご覧ください。ウィジェットの構成はウェブアプリにも適用されます。
省略可: この専用のウェブアプリから検索アプリをユーザーに提供するには、URL をコピーして、ログイン認証情報を持つユーザーに送信します。ユーザーは、ウェブアプリの URL をブックマークに登録して、その URL にアクセスして検索アプリを使用できます。

検索結果の取得について詳しくは、検索結果を取得するをご覧ください。