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

메모리 뱅크를 사용하면 범위 속성에 따라 메모리 및 메모리 수정 버전 리소스에 대한 액세스를 제어할 수 있습니다. IAM 조건을 사용하여 Common Expression Language에 정의된 기준에 따라 특정 사용자 또는 그룹에 대한 액세스를 제한하는 등 세부적인 액세스 제어를 정의할 수 있습니다.

이 문서에서는 프로젝트의 메모리와 수정사항에 대한 조건부 액세스 정책을 만들고 적용하는 방법을 설명합니다.

권한에 관한 개요 정보는 필요한 역할 검토를 참고하세요.

개요

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

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

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

시작하기 전에

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

• IAM 조건 검토: IAM 조건 개요를 숙지합니다.
• 필요한 역할 확인: 최소 권한의 원칙을 보장하기 위해 사용 사례에 적합한 특수 메모리 뱅크 IAM 역할을 확인합니다.

• 영향을 받는 주 구성원 식별: 조직에서 어떤 사용자에게 어떤 권한을 부여해야 하는지 식별합니다. 예를 들어 다음을 고려해 보세요.

  • 개발자가 모든 추억을 볼 수 있는지 여부입니다.
  • 프로젝트 관리자가 모든 추억을 볼 수 있는지 여부입니다.
  • 특정 에이전트 ID가 특정 메모리에만 액세스할 수 있는지 여부입니다.
• IAM 역할 부여: 이 문서의 작업을 수행하는 데 필요한 권한이 포함된 필수 역할이 있는지 확인합니다.

  에이전트 플랫폼 메모리 뱅크 리소스에 IAM 조건을 적용하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

  • 프로젝트의 경우: 프로젝트 IAM 관리자 (`roles/resourcemanager.projectIamAdmin`)

  역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

  이러한 사전 정의된 역할에는 에이전트 플랫폼 메모리 뱅크 리소스에 IAM 조건을 적용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

  필수 권한

  Agent Platform 메모리 뱅크 리소스에 IAM 조건을 적용하려면 다음 권한이 필요합니다.

  • 프로젝트 수준에서 조건부 IAM 액세스 권한 설정: `resourcemanager.projects.setIamPolicy`

  커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

  조직 전체에 IAM 조건을 사용하려면 조직 정책을 관리할 수 있는 권한도 필요합니다.

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

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

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

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

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"
  }
}

범위 수준 권한 권장사항

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

1. 특수 메모리 뱅크 역할 사용: 메모리 뱅크 IAM 조건은 메모리 및 메모리 수정사항에 적용되는 역할에만 사용해야 합니다. aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor, aiplatform.googleapis.com/memoryUser와 같은 전문 역할을 사용하여 과도한 액세스를 방지할 수 있습니다. 자세한 내용은 특수 메모리 뱅크 IAM 역할을 참고하세요.

2. 긍정 조건 사용: 정확도를 높이려면 aiplatform.googleapis.com/memoryScope에서 긍정 조건 (예: 키-값 쌍의 동일성 또는 존재 여부 확인)을 사용하는 것이 좋습니다. 지원되지 않는 유형과 서비스는 빈 범위로 표시되므로 부등식 확인과 같은 부정 조건이 의도치 않게 광범위한 리소스와 일치할 수 있습니다. 이로 인해 과도한 권한이 부여되고 예상치 못한 권한 부여가 허용될 수 있습니다.

3. 가능한 경우 조건 단축: 특히 많은 조건을 사용할 계획이라면 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'를 사용할 수 있습니다. user_id 키가 누락되면 긴 표현식은 false로 평가되고 짧은 표현식은 오류가 발생합니다. IAM 조건 표현식의 오류로 인해 액세스가 거부되므로 두 표현식 모두 동일한 결과를 생성합니다.

특수 메모리 뱅크 IAM 역할

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

메모리 뱅크에서 IAM 조건 사용

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

1. 범위가 정확히 일치하는 추억에 대한 읽기 액세스 권한을 부여합니다.

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

3. 특정 키를 포함하는 범위로 추억에 대한 전체 액세스 권한을 부여합니다.

4. 특정 접두사를 포함하는 범위로 추억에 대한 전체 액세스 권한을 부여합니다.

5. 허용된 값 집합으로 키의 범위가 지정된 추억에 대한 전체 액세스 권한을 부여합니다.

정확한 범위 일치로 추억에 대한 읽기 액세스 권한 부여

다음 조건은 정확한 범위가 {"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 그룹 사용자(보기 권한 사용자 및 편집자)에게 부여합니다.

즉, 그룹의 구성원은 {'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'] in ['userA', 'userB']"
  }
}

제한사항

• 주 구성원 한도: IAM 정책은 고유한 주 구성원 1,500명으로 제한됩니다. 이 한도는 Google 그룹스를 사용하여 관리할 수 있습니다. 모든 주 구성원의 한도에서 자세히 알아보세요.

• API 지원: ListMemories 및 PurgeMemories와 같이 여러 범위에 대해 작동하는 메서드는 IAM 조건을 지원하지 않습니다. 이러한 권한을 부여하려면 주 구성원에게 aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser 또는 관련 무조건 Gemini Enterprise Agent Platform 역할과 같은 무조건 역할을 부여해야 합니다.