데이터 소스 액세스 제어 사용

이 페이지에서는 Vertex AI Agent Builder에서 검색 앱에 데이터 소스 액세스 제어를 적용하는 방법을 설명합니다.

Vertex AI Agent Builder의 데이터 소스에 대한 액세스 제어는 사용자가 검색 앱의 결과에서 볼 수 있는 데이터를 제한합니다. Google은 ID 공급업체를 사용하여 검색을 수행하는 최종 사용자를 식별하고 결과로 반환되는 문서에 액세스할 수 있는지 확인합니다.

예를 들어 회사의 직원이 검색 앱을 사용하여 Confluence 문서를 검색한다고 가정해 보겠습니다. 하지만 액세스 권한이 없는 직원은 앱을 통해 콘텐츠를 볼 수 없도록 해야 합니다. 조직의 ID 공급업체에 대해 Google Cloud에서 직원 풀을 설정한 경우 Vertex AI Agent Builder에서 해당 직원 풀을 지정할 수도 있습니다. 이제 직원이 앱을 사용하면 계정이 Confluence에서 이미 액세스할 수 있는 문서의 검색 결과만 표시됩니다.

데이터 소스 액세스 제어 정보

액세스 제어를 사용 설정하는 것은 일회성 절차입니다.

Cloud Storage, BigQuery, Google Drive, 모든 서드 파티 데이터 소스에 액세스 제어를 사용할 수 있습니다.

Vertex AI Agent Builder에 데이터 소스 액세스 제어를 사용 설정하려면 Google Cloud에 조직의 ID 공급업체가 구성되어 있어야 합니다. 지원되는 인증 프레임워크는 다음과 같습니다.

Google ID: Google ID를 사용하는 경우 모든 사용자 ID 및 사용자 그룹이 Google Cloud를 통해 표시되고 관리됩니다. Google ID에 대한 자세한 내용은 Google ID 문서를 참조하세요.
서드 파티 ID 공급업체 제휴: Okta 또는 Azure AD와 같은 외부 ID 공급업체를 사용하는 경우 Vertex AI Agent Builder의 데이터 소스 액세스 제어를 사용 설정하기 전에 Google Cloud에서 직원 ID 제휴를 설정해야 합니다.

서드 파티 커넥터를 사용하는 경우 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에서 지원하는 위치당 하나의 ID 공급업체를 선택할 수 있습니다.
액세스 제어는 ID 공급업체에 명시적으로 정의된 ID 및 그룹에 대해서만 적용됩니다. 서드 파티 앱 내에서 기본적으로 정의된 ID 또는 그룹은 지원되지 않습니다.
데이터 소스를 액세스 제어로 설정하려면 데이터 스토어를 만들 때 이 설정을 선택해야 합니다. 기존 데이터 스토어의 경우 이 설정을 사용 또는 사용 중지할 수 없습니다.
콘솔의 데이터 > 문서 탭에는 액세스가 제어된 데이터 소스의 데이터가 표시되지 않습니다. 이 데이터는 보기 권한이 있는 사용자에게만 표시되어야 하기 때문입니다.
서드 파티 액세스 제어를 사용하는 검색 앱의 UI 결과를 미리보려면 제휴 콘솔에 로그인하거나 웹 앱을 사용해야 합니다. 액세스 제어된 앱의 결과 미리보기를 참조하세요.

시작하기 전에

이 절차에서는 Google Cloud 프로젝트에서 ID 공급업체를 설정했다고 가정합니다.

Google ID: Google ID를 사용하는 경우 ID 공급업체에 연결 절차를 진행할 수 있습니다.
서드 파티 ID 공급업체: 서드 파티 ID 공급업체의 직원 ID 풀을 설정했는지 확인합니다. 직원 풀을 설정할 때 대상 및 그룹 속성 매핑을 지정했는지 확인합니다. 속성 매핑에 대한 자세한 내용은 IAM 문서의 속성 매핑을 참조하세요. 직원 ID 풀 관리에 대한 자세한 내용은 IAM 문서의 직원 ID 풀 제공업체 관리를 참조하세요.

ID 공급업체에 연결

Vertex AI Agent Builder의 ID 공급업체를 지정하고 데이터 소스 액세스 제어를 사용 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

Agent Builder를 사용하여 이 모든 것을 자체 데이터에 그라운딩하세요.
설정 > 인증 페이지로 이동합니다.
업데이트할 위치에 대해 ID 공급업체 추가를 클릭합니다.
ID 공급업체 추가 대화상자에서 ID 공급업체를 선택합니다. 서드 파티 ID 공급업체를 선택하는 경우 데이터 소스에 적용되는 직원 풀도 선택합니다.
변경사항 저장을 클릭합니다.

액세스 제어가 포함된 데이터 소스 구성

데이터 소스에 액세스 제어를 적용하려면 설정하는 데이터 소스의 유형에 따라 다음 단계를 따르세요.

서드 파티 데이터 소스: 앱을 만들 때 추가 구성이 필요하지 않습니다. 서드 파티 액세스 제어가 포함된 앱의 결과 미리보기로 건너뜁니다.
Google Drive: 앱을 만들 때 추가 구성이 필요하지 않습니다.
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 결과를 미리보는 방법은 두 가지가 있습니다.

직원 ID 제휴 콘솔. 직원 ID 제휴 콘솔을 열고 서드 파티 사용자 인증 정보로 로그인합니다. 직원 ID 제휴 콘솔에서 결과 미리보기를 참조하세요.
웹 앱. Vertex AI Search에서 제공하는 전용 웹 앱을 사용 설정하고 로그인합니다. 웹 앱 사용 설정을 참조하세요.

직원 ID 제휴 콘솔에서 결과 미리보기

직원 ID 제휴 콘솔을 사용하여 결과를 보려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

Agent Builder를 사용하여 이 모든 것을 자체 데이터에 그라운딩하세요.
결과를 미리보려는 검색 앱의 이름을 클릭합니다.
미리보기 페이지로 이동합니다.
제휴 ID로 미리보기를 클릭하여 직원 ID 제휴 콘솔로 이동합니다.
직원 풀 제공업체 및 조직의 사용자 인증 정보를 입력합니다.
표시되는 미리보기 페이지에서 앱의 결과를 미리봅니다.

검색 결과 미리보기에 대한 자세한 내용은 검색 결과 가져오기를 참조하세요.

직원 ID 제휴 콘솔에 대한 자세한 내용은 콘솔(제휴) 정보를 참조하세요.

사용자에게 검색 권한 부여

사용자에게 앱을 사용하여 액세스가 제어된 데이터를 검색할 수 있는 기능을 제공하려면 도메인 또는 직원 풀의 사용자에게 액세스 권한을 부여해야 합니다. 사용자 그룹에 커스텀 IAM 역할을 부여하는 것이 좋습니다.

Google ID: Google ID를 사용하는 경우 검색해야 하는 모든 직원이 포함된 Google 그룹을 만드는 것이 좋습니다. Google Workspace 관리자는 조직의 모든 사용자를 하나의 그룹에 추가하기의 단계에 따라 조직의 모든 사용자를 Google 그룹에 포함할 수 있습니다.
서드 파티 ID 공급업체: Okta 또는 Azure AD와 같은 외부 ID 공급업체를 사용하는 경우 직원 풀의 모든 사용자를 하나의 그룹에 추가합니다.

다음 권한을 사용하여 사용자 그룹에 부여할 커스텀 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를 호출해야 하는 도메인 또는 직원 풀의 사용자에게 검색 엔진 뷰어 역할을 부여합니다.
위젯에 전달할 승인 토큰을 생성합니다.
- Google ID: OAuth 2.0 액세스 토큰을 생성합니다.
- 직원 ID 제휴: 직원 ID 제휴를 위한 단기 토큰 가져오기의 단계에 따라 토큰을 가져옵니다.
승인 토큰이 있는 위젯 추가의 단계에 따라 토큰을 위젯에 전달합니다.

웹 앱 사용 설정

웹 앱은 Vertex AI Search에서 생성한 전용 사이트로, 개발자와 로그인 사용자 인증 정보가 있는 다른 모든 사용자가 검색 앱을 사용할 수 있습니다.

자체 애플리케이션에 검색 위젯이나 검색 API를 통합하지 않고 사용자에게 검색 앱을 제공하려면 사용자에게 웹 앱 URL을 제공하면 됩니다.

웹 앱을 사용 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.

Agent Builder를 사용하여 이 모든 것을 자체 데이터에 그라운딩하세요.
웹 앱을 만들 검색 앱의 이름을 클릭합니다.
통합 > UI 탭으로 이동합니다.
웹 앱 사용 설정을 클릭합니다.
직원 ID 제휴를 사용하는 경우 직원 풀 공급업체를 선택합니다.
웹 앱 링크를 클릭합니다.
직원 풀 제공업체 및 조직의 사용자 인증 정보를 입력합니다.
앱의 결과를 미리봅니다.
웹 앱의 결과를 구성하려면 검색 위젯의 결과 구성으로 이동합니다. 위젯의 구성은 웹 앱에도 적용됩니다.
선택사항: 이 전용 웹 앱을 통해 사용자에게 검색 앱을 제공하려면 URL을 복사하여 로그인 사용자 인증 정보가 있는 사용자에게 전송합니다. 웹 앱 URL을 북마크에 추가하고 이 URL로 이동하여 검색 앱을 사용할 수 있습니다.

검색 결과를 가져오는 방법에 대한 자세한 내용은 검색 결과 가져오기를 참조하세요.