IAM 조건으로 세션에 대한 액세스 제어

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

개요

IAM 조건을 사용하면 지정된 조건이 충족되는 경우에만 세션 및 세션 이벤트 리소스에 대한 액세스 권한을 부여할 수 있습니다. Common Expression Language로 작성된 표현식과 함께 API 속성 aiplatform.googleapis.com/sessionUserId를 사용하여 세션 리소스 내의 userId 문자열을 기반으로 세션 액세스를 제어할 수 있습니다. 사용자 ID는 userId = "userA"과 같이 세션을 만들 때 제공되는 임의의 문자열입니다.

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

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

시작하기 전에

세션 및 세션 이벤트에 대한 조건부 Identity and Access Management 정책을 설정하려면 다음 단계를 따르세요.

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

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

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

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

프로젝트 수준에서 Identity and Access Management 정책 바인딩에 조건을 추가하여 세션에 대한 조건부 액세스 권한을 부여합니다. 이 조건은 api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 함수를 사용하여 세션 리소스의 사용자 ID를 검사합니다. 세션을 만들 때 사용자 ID를 정의합니다.

조건이 있는 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/sessionUserId를 API 속성으로 사용하여 역할에 조건을 추가합니다. 가능한 조건문은 아래 예를 참고하세요.
저장을 클릭합니다. 주 구성원에게 리소스에 대한 역할이 부여됩니다.

gcloud

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

Google Cloud 콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
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/sessionUserId을 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       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

다음 변수를 바꿉니다.

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

사용자 ID 수준 권한에 관한 권장사항

세션에 대한 조건을 빌드할 때는 다음 권장사항을 따르세요.

전문 세션 IAM 역할 사용: 세션 IAM 조건은 세션 및 세션 이벤트에 적용되는 역할에만 사용해야 합니다. aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor, aiplatform.googleapis.com/sessionUser와 같은 전문 역할을 사용하여 과도한 액세스를 방지할 수 있습니다. 자세한 내용은 특수 세션 IAM 역할 섹션을 참고하세요.
긍정 조건 사용: 정확도를 높이려면 aiplatform.googleapis.com/sessionUserId에서 긍정 조건 (예: 동등성 확인 또는 접두사 존재 여부 확인)을 사용하는 것이 좋습니다. 지원되지 않는 유형과 서비스는 빈 사용자 ID로 표시되므로 부등식 확인과 같은 부정 조건이 의도치 않게 광범위한 리소스와 일치할 수 있으며, 이는 지나치게 허용적이고 예기치 않은 권한 부여를 허용할 수 있습니다.
가능한 경우 조건 단축: 특히 많은 조건을 사용할 계획이라면 IAM 조건 표현식 내에서 가장 짧고 간단한 논리를 사용하는 것이 좋습니다. IAM 허용 정책에는 크기 제한이 있으며 조건을 간소화하면 IAM 제한을 방지할 수 있습니다. 자세한 내용은 제한사항을 참고하세요. 예를 들어 api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB' 복합 문을 사용하면 api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'] 짧은 문과 동일한 결과가 나오므로 두 개의 서로 다른 사용자 ID를 더 간단하게 확인할 수 있습니다.

특수 세션 IAM 역할

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

역할 이름	설명	포함된 권한
`roles/aiplatform.sessionViewer`	세션 및 등록정보 이벤트에 대한 읽기 전용 액세스 권한을 부여합니다.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	세션에 대한 쓰기 액세스 권한과 이벤트 추가 권한을 부여합니다.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	모든 뷰어 및 편집자 권한을 포함하여 세션 및 이벤트에 대한 전체 액세스 권한을 부여합니다.	`sessionEditor` 및 `sessionViewer`의 모든 권한이 포함됩니다.

세션에 IAM 조건 사용

이 섹션에서는 세션과 함께 IAM 조건을 사용하는 다음 예시를 다룹니다.

사용자 ID가 정확히 일치하는 세션에 대한 읽기 액세스 권한을 부여합니다.
사용자 ID에 특정 접두사가 포함된 세션에 대한 쓰기 액세스 권한을 부여합니다.
두 사용자 ID 중 하나가 포함된 세션에 대한 전체 액세스 권한을 부여합니다.

정확한 사용자 ID가 일치하는 세션에 대한 읽기 액세스 권한 부여

다음 조건은 정확한 사용자 ID가 userA인 세션에만 개별 userA@gmail.com 보기 액세스 권한을 부여합니다.

즉, 사용자 ID가 정확히 userA인 경우 세션을 가져오고 세션 이벤트를 나열할 수 있습니다. 사용자가 userB와 같은 사용자 ID가 있는 세션에 액세스할 수 없습니다.

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

사용자 ID에 특정 접두사가 포함된 세션에 대한 쓰기 액세스 권한 부여

다음 조건은 user로 시작하는 사용자 ID가 포함된 모든 세션에 대해 개인 developerA@corp.com에게 수정 액세스 권한을 부여합니다. startsWith를 사용하여 접두사를 확인하고 endsWith를 사용하여 접미사를 확인할 수 있습니다.

즉, 개발자는 userA 또는 user1234과 같은 사용자 ID를 사용하여 세션을 만들고, 업데이트하고, 삭제할 수 있으며, 이벤트를 추가할 수 있습니다.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

두 사용자 ID 중 하나가 포함된 세션에 대한 전체 액세스 권한 부여

다음 조건은 그룹 group:engineering@corp.com 사용자 (뷰어 및 편집자)에게 사용자 ID가 userA 또는 user123인 세션에 대한 액세스 권한을 부여합니다.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

제한사항

주 구성원 한도: IAM 정책은 고유한 주 구성원 1,500개로 제한됩니다. 이 한도는 Google 그룹스를 사용하여 관리할 수 있습니다. 자세한 내용은 모든 주 구성원의 한도를 참고하세요.
ListSessions API 지원: ListSessions API는 IAM 조건을 지원하지 않습니다. ListSessions 권한을 부여하려면 주 구성원에게 aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser 또는 관련 무조건 Vertex AI 역할과 같은 무조건 역할을 부여해야 합니다.