IAM 조건으로 메모리 뱅크에 대한 액세스 제어

기본적으로 메모리 Identity and Access Management 권한은 프로젝트 수준입니다. 이 문서에서는 IAM 조건을 사용하여 Vertex AI Agent Engine 메모리 뱅크 리소스에 대한 액세스를 보다 세부적으로 제어하는 방법을 설명합니다.

개요

IAM 조건을 사용하면 지정된 조건이 충족되는 경우에만 메모리 및 메모리 버전 리소스에 대한 액세스 권한을 부여할 수 있습니다. Common Expression Language로 작성된 표현식과 함께 API 속성 "aiplatform.googleapis.com/memoryScope"을 사용하여 메모리 리소스 내의 scope 필드를 기반으로 메모리에 대한 액세스를 제어할 수 있습니다. 범위는 메모리를 만들거나 생성할 때 제공되는 임의의 사전으로, {'user_id': '123'}와 같이 어떤 메모리가 어떤 그룹에 속하는지 정리할 수 있습니다.

이러한 조건부 ID 및 액세스 관리 정책은 프로젝트 수준에서 생성되며 프로젝트 내의 모든 추억에 적용됩니다. 프로젝트 사용자 및 서비스 계정을 비롯한 모든 종류의 주 구성원에 IAM 조건을 적용할 수 있습니다.

IAM 조건은 아직 존재하지 않는 리소스를 포함하여 여러 관련 메모리 뱅크 리소스에 동시에 Identity and Access Management (IAM) 권한을 부여하는 데 유용합니다. 사용자가 자신의 정보에만 액세스할 수 있도록 또는 개발자가 특별한 권한 부여 없이 특정 메모리 뱅크 리소스만 볼 수 있도록 메모리 및 수정사항에 대한 액세스를 제한할 수 있습니다.

시작하기 전에

추억 및 추억 수정사항에 대한 조건부 IAM 정책을 설정하려면 다음 단계를 따르세요.

IAM 조건 검토: IAM 조건 개요를 숙지합니다.
필요한 역할 결정: 최소 권한의 원칙을 보장하기 위해 사용 사례에 적합한 특수 메모리 뱅크 IAM 역할을 식별합니다.
영향을 받는 주 구성원 식별: 조직에서 누가 어떤 권한을 받아야 하는지 식별합니다. 예를 들어 다음을 고려해 보세요.
- 개발자가 모든 추억을 볼 수 있는지 여부입니다.
- 프로젝트 관리자가 모든 추억을 볼 수 있는지 여부입니다.
- 특정 에이전트 ID가 특정 메모리에만 액세스할 수 있는지 여부입니다.
IAM 역할 부여: 이 문서의 작업을 수행하는 데 필요한 권한이 포함된 필수 역할이 있는지 확인합니다.
Vertex AI Agent Engine 메모리 저장소 리소스에 IAM 조건을 적용하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.
- 프로젝트의 경우: 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 Vertex AI Agent Engine Memory Bank 리소스에 IAM 조건을 적용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한

Vertex AI Agent Engine 메모리 뱅크 리소스에 IAM 조건을 적용하려면 다음 권한이 필요합니다.
- 프로젝트 수준에서 조건부 IAM 액세스 권한을 설정합니다. resourcemanager.projects.setIamPolicy
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
조직 전체에 IAM 조건을 사용하려면 조직 정책을 관리할 수 있는 권한도 필요합니다.

추억에 대한 조건부 액세스 만들기

추억에 대한 조건부 액세스 권한은 프로젝트 수준에서 IAM 정책 바인딩에 조건을 추가하여 부여됩니다. 조건에서는 api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) 함수를 사용하여 메모리 리소스의 범위 맵을 검사합니다. 기억을 만들거나 생성할 때 범위를 정의합니다.

조건이 있는 IAM 정책을 만드는 방법에 관한 자세한 가이드는 허용 정책의 조건을 참고하세요.

주 구성원에 단일 역할을 부여하려면 다음을 수행합니다.

콘솔

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

IAM으로 이동
프로젝트를 선택합니다.
역할을 부여할 주 구성원을 선택합니다.
- 리소스에 대해 이미 다른 역할이 있는 주 구성원에게 역할을 부여하려면 주 구성원이 포함된 행을 찾아 해당 행에서 주 구성원 수정을 클릭하고 다른 역할 추가를 클릭합니다.
  
  서비스 에이전트에 역할을 부여하려면 Google제공 역할 부여 포함 체크박스를 선택하여 이메일 주소를 확인합니다.
  
  참고: 리소스에 대해 액세스를 관리할 때 상속된 역할은 수정할 수 없습니다. 상속된 역할을 수정하려면 해당 역할이 부여된 리소스로 이동합니다.
- 리소스에 대한 기존 역할이 없는 주 구성원에게 역할을 부여하려면 액세스 권한 부여를 클릭한 후 주 구성원 식별자(예: my-user@example.com 또는 //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com)를 입력합니다.
드롭다운 목록에서 부여할 역할을 선택합니다. 보안 권장사항에 따라 주 구성원에게 필요한 권한만 포함된 역할을 선택합니다. 특수 메모리 뱅크 IAM 역할 중 하나를 선택할 수 있습니다.
aiplatform.googleapis.com/memoryScope를 API 속성으로 사용하여 역할에 조건을 추가합니다. 가능한 조건문은 아래 예를 참고하세요.
저장을 클릭합니다. 주 구성원에게 리소스에 대한 역할이 부여됩니다.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
add-iam-policy-binding 명령어를 사용하면 주 구성원에게 역할을 빠르게 부여할 수 있습니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다. 프로젝트 ID는 my-project와 같은 영숫자입니다.
- PRINCIPAL: 주 구성원이나 구성원의 식별자로, 대개 PRINCIPAL_TYPE:ID 형식을 따릅니다. 예를 들면 user:my-user@example.com 또는 principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com입니다. PRINCIPAL에 지정할 수 있는 전체 값 목록은 주 구성원 식별자를 참조하세요.
  
  주 구성원 유형 user의 경우 식별자의 도메인 이름은 Google Workspace 도메인이나 Cloud ID 도메인이어야 합니다. Cloud ID 도메인을 설정하는 방법은 Cloud ID 개요를 참조하세요.
- ROLE_NAME: 취소할 역할의 이름입니다. 다음 형식 중 하나를 사용하세요.
  - 사전 정의된 역할: roles/aiplatform.IDENTIFIER
  - 프로젝트 수준 커스텀 역할: projects/PROJECT_ID/roles/IDENTIFIER
  드롭다운 목록에서 부여할 역할을 선택합니다. 보안 권장사항에 따라 주 구성원에게 필요한 권한만 포함된 역할을 선택합니다. 특수 메모리 뱅크 IAM 역할 중 하나를 선택할 수 있습니다.
- CONDITION: aiplatform.googleapis.com/memoryScope을 API 속성으로 사용하여 역할에 조건을 추가합니다. 가능한 조건문은 아래 예를 참고하세요.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION
```
Windows(PowerShell)
```
gcloud projects add-iam-policy-binding PROJECT_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION
```
Windows(cmd.exe)
```
gcloud projects add-iam-policy-binding PROJECT_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION
```
응답에는 업데이트된 IAM 정책이 포함됩니다.

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요. 자세한 내용은 Terraform 제공업체 참고 문서를 확인하세요.

Terraform을 사용하여 IAM 정책을 설정하는 경우 google_project_iam_member 리소스에 조건을 포함하여 구성원의 추억 액세스를 제한할 수 있습니다.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

다음 변수를 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다. 프로젝트 ID는 my-project와 같은 영숫자입니다.
ROLE: 부여할 IAM 역할(예: roles/aiplatform.memoryEditor)
MEMBER: 역할을 부여할 주 구성원(예: user:developerA@corp.com) MEMBER에 지정할 수 있는 전체 값 목록은 주 구성원 식별자를 참고하세요.
CONDITION: API 속성으로 aiplatform.googleapis.com/memoryScope를 사용하는 IAM 조건문입니다. 가능한 조건문은 아래 예를 참고하세요.

범위 수준 권한 권장사항

메모리 뱅크의 조건을 빌드할 때는 다음 권장사항을 따르세요.

특화된 메모리 뱅크 역할 사용: 메모리 뱅크 IAM 조건은 메모리 및 메모리 수정사항에 적용되는 역할에만 사용해야 합니다. aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor, aiplatform.googleapis.com/memoryUser와 같은 전문 역할을 사용하여 과도한 액세스를 방지할 수 있습니다. 자세한 내용은 특수 메모리 뱅크 IAM 역할을 참고하세요.
긍정 조건 사용: 정확도를 높이려면 aiplatform.googleapis.com/memoryScope에서 긍정 조건 (예: 같음 또는 키-값 쌍의 존재 여부 확인)을 사용하는 것이 좋습니다. 지원되지 않는 유형과 서비스는 빈 범위로 표시되므로 부등식 확인과 같은 부정 조건이 의도치 않게 광범위한 리소스와 일치할 수 있으며, 이로 인해 과도한 권한이 부여되어 예상치 못한 권한 부여가 허용될 수 있습니다.
가능한 경우 조건 단축: 특히 많은 조건을 사용할 계획이라면 IAM 조건 표현식 내에서 가장 짧고 간단한 논리를 사용하는 것이 좋습니다. IAM 허용 정책에는 크기 제한이 있으며 조건을 단순화하면 이러한 IAM 제한을 방지할 수 있습니다. 자세한 내용은 제한사항을 참고하세요. 예를 들어 'user_id' in "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' 표현식에서 키의 존재 여부를 확인하지 않아도 됩니다. api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'이라는 더 짧은 문과 동일한 결과가 나오기 때문입니다.

특수 메모리 뱅크 IAM 역할

IAM 조건을 사용할 때는 과도한 권한이 부여된 IAM 정책을 방지하는 것이 중요합니다. 다음 표에는 Memory Bank API에 조건부 IAM 역할을 부여할 때 사용할 수 있는 전문 역할이 나와 있습니다.

역할 이름	설명	포함된 권한
`roles/aiplatform.memoryViewer`	추억 및 추억 수정사항에 대한 읽기 전용 액세스 권한을 부여합니다.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	메모리에 대한 쓰기 및 생성 액세스 권한과 메모리 수정사항에 대한 롤백 액세스 권한을 부여합니다.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	모든 뷰어 및 편집자 권한을 포함하여 메모리 및 수정사항에 대한 전체 액세스 권한을 부여합니다.	`memoryEditor` 및 `memoryViewer`의 모든 권한이 포함됩니다.

Memory Bank에서 IAM 조건 사용

이 섹션에서는 메모리 뱅크와 함께 IAM 조건을 사용하는 다음 예시를 다룹니다.

범위가 정확히 일치하는 추억에 대한 읽기 액세스 권한을 부여합니다.
특정 키-값 쌍이 포함된 범위로 메모리에 대한 쓰기 액세스 권한을 부여합니다.
특정 키를 포함하는 범위로 추억에 대한 전체 액세스 권한을 부여합니다.
특정 접두사가 포함된 범위의 추억에 대한 전체 액세스 권한을 부여합니다.
허용된 값 집합이 있는 키 범위로 추억에 대한 전체 액세스 권한을 부여합니다.

범위가 정확히 일치하는 기억에 대한 읽기 액세스 권한 부여

다음 조건은 정확한 범위가 {"userId": "userA"}인 메모리에만 개인 userA@gmail.com 보기 액세스 권한을 부여합니다.

즉, 범위가 정확히 {"userId": "userA"}인 경우 회원은 메모리를 가져오고 검색할 수 있으며, 해당 메모리의 수정사항을 나열하고 가져올 수 있습니다. 사용자가 {'userId': 'userA', 'source': 'ADK'}와 같은 범위가 있는 메모리에 액세스할 수 없습니다.

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

특정 키-값 쌍이 포함된 범위로 메모리에 대한 쓰기 액세스 권한 부여

다음 조건은 키-값 쌍 'userId': 'userA'이 포함된 모든 추억에 대해 개인 developerA@corp.com에게 수정 액세스 권한을 부여합니다.

즉, 사용자는 {'userId': 'userA'}, {'userId': 'userA', 'source': 'ADK'}과 같은 범위로 메모리를 생성, 업데이트, 삭제, 생성하고 이러한 메모리의 버전을 생성하고 롤백할 수 있습니다.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

특정 키가 포함된 범위로 추억에 대한 전체 액세스 권한 부여

다음 조건은 그룹 group:engineering@corp.com 사용자 (뷰어 및 편집자)에게 키가 'admin_override' 또는 'public_access_flag'인 메모리에 대한 액세스 권한을 부여합니다.

즉, 그룹 구성원은 {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'}, {'userId': 'userA', 'public_access_flag': 'false'}와 같은 범위의 추억에 대한 전체 읽기 및 쓰기 액세스 권한을 갖습니다.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

특정 접두사가 포함된 범위로 추억에 대한 전체 액세스 권한 부여

다음 조건은 'user'로 시작하는 값이 있는 키 'userId'가 있는 추억에 대한 액세스 권한을 그룹 group:engineering@corp.com 사용자 (뷰어 및 편집자)에게 부여합니다.'startsWith'를 사용하여 접두사를 확인하고 'endsWith'를 사용하여 접미사를 확인할 수 있습니다.

즉, 그룹 구성원은 {'userId': 'userA'}, {'userId': 'userB', 'public_access_flag': 'false'}과 같은 범위의 추억에 대한 모든 읽기 및 쓰기 액세스 권한을 갖습니다.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

허용된 값 집합이 있는 키 범위로 추억에 대한 전체 액세스 권한 부여

다음 조건은 'userA' 또는 'userB' 값이 있는 키 'userId'이 있는 메모리에 그룹 group:engineering@corp.com 사용자 (뷰어 및 편집자) 액세스 권한을 부여합니다.