使用 IAM 條件控管工作階段存取權

根據預設，工作階段身分與存取權管理權限位於專案層級。本文說明如何使用 IAM Conditions，以更精細的方式控管 Vertex AI Agent Engine Sessions 資源的存取權。

總覽

IAM Conditions 可讓您僅在符合指定條件時，授予工作階段和工作階段事件資源的存取權。您可以使用 API 屬性 aiplatform.googleapis.com/sessionUserId，並以通用運算式語言撰寫運算式，根據工作階段資源中的 userId 字串控管工作階段存取權。使用者 ID 是建立工作階段時提供的任意字串，例如 userId = "userA"。

這些有條件的身分與存取權管理政策是在專案層級建立，並套用至專案中的所有工作階段和工作階段事件。您可以對所有類型的主體套用 IAM 條件，包括專案使用者和服務帳戶。

IAM 條件可同時將身分與存取權管理 (IAM) 權限授予多個相關工作階段資源，包括尚未建立的資源。您可以限制工作階段和活動的存取權，讓使用者只能存取自己的資訊，或讓開發人員只能查看特定工作階段資源，不必授予特殊權限。

事前準備

如要為工作階段和工作階段事件設定有條件的 Identity and Access Management 政策，請按照下列步驟操作：

檢閱 IAM 條件：請先參閱 IAM 條件總覽。
判斷必要角色：找出適合您用途的專屬工作階段 IAM 角色，確保遵循最低權限原則。
找出受影響的主體：找出貴機構中應獲得哪些權限的使用者。舉例來說，請參考以下內容：
- 使用者是否應能查看其他使用者的工作階段？
- 開發人員是否應能查看所有工作階段？
- 專案管理員是否應能查看所有工作階段？
- 特定服務專員身分是否應能存取特定工作階段？
授予 IAM 角色：請確認您具備必要角色，其中包含執行本文件工作所需的權限。
如要取得對 Vertex AI Agent Engine Session 資源套用 IAM 條件所需的權限，請要求管理員授予您下列 IAM 角色：
- 專案：專案 IAM 管理員 (`roles/resourcemanager.projectIamAdmin`)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備權限，可將 IAM 條件套用至 Vertex AI Agent Engine 工作階段資源。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限

如要將 IAM 條件套用至 Vertex AI Agent Engine 工作階段資源，必須具備下列權限：
- 在專案層級設定條件式 IAM 存取權： `resourcemanager.projects.setIamPolicy`
您或許還可透過自訂角色或其他預先定義的角色取得這些權限。
如果您打算在整個機構中使用 IAM 條件，也需要管理機構政策的權限。

為工作階段建立條件存取權

在專案層級的 Identity and Access Management 政策繫結中新增條件，即可授予工作階段條件式存取權。條件會使用 api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 函式檢查工作階段資源的 User-ID。您可以在建立工作階段時定義使用者 ID。

如需建立含條件 IAM 政策的詳細指南，請參閱「允許政策中的條件」。

如要將單一角色授予主體，請執行下列步驟：

控制台

前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

前往 IAM
選取專案。
選取要授予角色的主體：
- 如要將角色授予資源上已有其他角色的主體，請找出包含該主體的列，依序點選該列的「Edit principal」(編輯主體) 和「Add another role」(新增其他角色)。
  
  如要將角色授予服務代理，請選取「包含 Google 提供的角色授予項目」核取方塊，查看服務代理的電子郵件地址。Google
  
  注意： 管理資源存取權時，您無法編輯沿用的角色。如要編輯沿用的角色，請前往授予角色的資源。
- 如要將角色授予資源上還沒有任何角色的主體，請點選「Grant Access」(授予存取權)，然後輸入主體 ID，例如 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：主體或成員的 ID，通常採用以下形式： PRINCIPAL_TYPE:ID。例如 user:my-user@example.com 或 principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。如需 PRINCIPAL 可擁有的完整值清單，請參閱「主體 ID」。
  
  如果是 user 主體類型，識別碼中的網域名稱必須是 Google Workspace 網域或 Cloud Identity 網域。如要瞭解如何設定 Cloud Identity 網域，請參閱 Cloud Identity 總覽。
- 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 可擁有的完整值清單，請參閱「主體 ID」。
CONDITION：您的 IAM 條件陳述式，使用 aiplatform.googleapis.com/sessionUserId 做為 API 屬性。請參閱下方的範例，瞭解可能的條件陳述式。

使用者 ID 層級權限的最佳做法

建立工作階段條件時，請遵循下列最佳做法：

使用專屬的工作階段 IAM 角色：工作階段 IAM 條件僅適用於工作階段和工作階段事件適用的角色。您可以運用 aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionEditor 和 aiplatform.googleapis.com/sessionUser 等專門角色，避免過度寬鬆的存取權。詳情請參閱「專屬工作階段 IAM 角色」一節。
使用正向條件：建議在 aiplatform.googleapis.com/sessionUserId 上使用正向條件 (例如檢查等號或前置字元是否存在)，以提高準確度。由於系統會以空白的使用者 ID 代表不支援的類型和服務，因此負面條件 (例如不相等檢查) 可能會意外比對大量資源，導致權限過於寬鬆，並允許授予非預期的權限。
盡可能縮短條件：建議您在 IAM 條件運算式中使用最短且最簡單的邏輯，尤其是當您打算設定大量條件時。IAM 允許政策有大小限制，簡化條件可避免遇到 IAM 限制。詳情請參閱「限制」一節。舉例來說，您可以合併複合陳述式，簡化檢查兩個不同使用者 ID 的程序：api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB'，因為這與較短的陳述式 api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'] 評估結果相同。

專屬工作階段 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 含有特定前置字元的工作階段寫入權。
授予包含其中一個 User ID 的工作階段完整存取權。

授予與使用者 ID 完全相符的工作階段讀取權限

下列條件只會授予使用者 userA@gmail.com 檢視權限，但僅限於具有完全相同 User ID userA 的工作階段。

也就是說，只要使用者 ID 完全符合 userA，該使用者就能取得工作階段並列出工作階段事件。使用者無法存取具有使用者 ID (例如 userB) 的工作階段。

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

授予含有特定前置字元的使用者 ID 工作階段寫入權

以下條件會授予個人使用者developerA@corp.com編輯權限，可編輯任何包含以 user 開頭的使用者 ID 的工作階段。你可以使用 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 政策最多只能有 1500 個不重複的主體。您可以使用 Google 群組管理這項限制。詳情請參閱「所有主體的限制」。
ListSessions API 支援：ListSessions API 不支援 IAM 條件。如要授予 ListSessions 權限，您必須授予主體無條件角色，例如 aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionUser 或相關的無條件 Vertex AI 角色。