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

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/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: API 속성으로 aiplatform.googleapis.com/sessionUserId를 사용하는 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 역할과 같은 무조건 역할을 부여해야 합니다.