Policy

Identity and Access Management (IAM) 政策，用於指定 Google Cloud 資源的存取權控管。

Policy 是 bindings 的集合。binding 會將一或多個 members 或主體繫結至單一 role。主體可以是使用者帳戶、服務帳戶、Google 群組和網域 (例如 G Suite)。role 是具名的權限清單，每個 role 都可以是 IAM 預先定義的角色，或是使用者建立的自訂角色。

對於某些類型的 Google Cloud 資源，binding 也可以指定 condition，這是邏輯運算式，只有在運算式評估結果為 true 時，才允許存取資源。條件可根據要求、資源或兩者的屬性新增限制。如要瞭解哪些資源的 IAM 政策支援條件，請參閱 IAM 說明文件。

JSON 範例：

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:mike@example.com",
            "group:admins@example.com",
            "domain:google.com",
            "serviceAccount:my-project-id@appspot.gserviceaccount.com"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:eve@example.com"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

YAML 範例：

    bindings:
    - members:
      - user:mike@example.com
      - group:admins@example.com
      - domain:google.com
      - serviceAccount:my-project-id@appspot.gserviceaccount.com
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:eve@example.com
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

如需 IAM 及其功能的說明，請參閱 IAM 說明文件。

JSON 表示法 
{
  "version": integer,
  "bindings": [
    {
      object (Binding)
    }
  ],
  "auditConfigs": [
    {
      object (AuditConfig)
    }
  ],
  "etag": string
}
欄位
version

integer

指定政策格式。

有效值為 0、1 和 3。如果要求指定無效值，系統會拒絕要求。

凡是會影響條件式角色繫結的作業，都必須指定版本 3。這項規定適用於下列作業：

  • 取得包含條件式角色繫結的政策
  • 在政策中新增條件角色繫結
  • 變更政策中的條件式角色繫結
  • 從包含條件的政策中移除任何角色繫結 (無論是否包含條件)

重要事項：如果您使用 IAM 條件，每次呼叫 setIamPolicy 時，都必須加入 etag 欄位。如果省略這個欄位，IAM 允許您以版本 1 政策覆寫版本 3 政策，且版本 3 政策中的所有條件都會遺失。

如果政策不含任何條件，對該政策執行的作業可以指定任何有效版本，或將欄位留空。

如要瞭解哪些資源的 IAM 政策支援條件，請參閱 IAM 說明文件。
bindings[]

object (Binding)

將 members 清單或主體與 role 建立關聯。(選用) 您可以指定 condition，決定 bindings 的套用方式和時間。每個 bindings 至少必須包含一個主體。

Policy 中的 bindings 最多可參照 1,500 個主體，其中最多 250 個主體可以是 Google 群組。每個主體例項都會計入這些限制。舉例來說，如果 bindings 將 50 個不同的角色授予 user:alice@example.com，但未授予任何其他主體，則您可以在 Policy 中將另外 1,450 個主體新增至 bindings。
auditConfigs[]

object (AuditConfig)

指定此政策的雲端稽核記錄設定。
etag

string (bytes format)

etag 用於開放式並行控制，有助防止政策在同時更新時相互覆寫。強烈建議系統在讀取-修改-寫入週期中使用 etag 執行政策更新，以避免發生競爭狀況：系統會在 getIamPolicy 的回應中傳回 etag，並將該 etag 放入 setIamPolicy 的要求中，確保變更會套用至相同版本的政策。

重要事項：如果您使用 IAM 條件，每次呼叫 setIamPolicy 時，都必須加入 etag 欄位。如果省略這個欄位，IAM 允許您以版本 1 政策覆寫版本 3 政策，且版本 3 政策中的所有條件都會遺失。

Base64 編碼字串。

繫結

將 members (或主體) 與 role 建立關聯。

JSON 表示法 
{
  "role": string,
  "members": [
    string
  ],
  "condition": {
    object (Expr)
  }
}
欄位
role

string

指派給 members 或主體清單的角色。例如 roles/viewer、roles/editor 或 roles/owner。

如要瞭解身分與存取權管理角色和權限，請參閱身分與存取權管理說明文件。如需可用預先定義角色的清單，請參閱這裡。
members[]

string

指定向 Google Cloud 資源要求存取權的主體。members 的值可能如下：

  • allUsers：這種特殊的身分識別代表網際網路上的所有使用者，無論該使用者是否有 Google 帳戶。

  • allAuthenticatedUsers：這種特殊的身分識別代表任何透過 Google 帳戶或服務帳戶進行驗證的使用者。不包括透過身分聯盟從外部身分提供者 (IdP) 取得的身分。

  • user:{emailid}：代表特定 Google 帳戶的電子郵件地址，例如：alice@example.com。

  • serviceAccount:{emailid}：代表 Google 服務帳戶的電子郵件地址，例如：my-other-app@appspot.gserviceaccount.com。

  • serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]：Kubernetes 服務帳戶的 ID。例如：my-project.svc.id.goog[my-namespace/my-kubernetes-sa]。

  • group:{emailid}：代表 Google 群組的電子郵件地址，例如：admins@example.com。

  • domain:{domain}：代表該網域所有使用者的 G Suite 網域 (主要)，例如 google.com 或 example.com。

  • principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}：工作團隊身分集區中的單一身分。

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/group/{groupId}：群組中的所有員工身分。

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/attribute.{attribute_name}/{attribute_value}：具有特定屬性值的所有員工身分。

  • principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/*：工作團隊身分集區中的所有身分。

  • principal://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/subject/{subject_attribute_value}：workload identity pool 中的單一身分。

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/group/{groupId}：Workload Identity 集區群組。

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/attribute.{attribute_name}/{attribute_value}：workload identity pool 中具有特定屬性的所有身分。

  • principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/*：Workload Identity 集區中的所有身分。

  • deleted:user:{emailid}?uid={uniqueid}：代表最近刪除的使用者電子郵件地址 (加上專屬 ID)。例如：alice@example.com?uid=123456789012345678901。如果使用者已復原，這個值會還原為 user:{emailid}，且復原的使用者會保留繫結中的角色。

  • deleted:serviceAccount:{emailid}?uid={uniqueid}：代表最近刪除的服務帳戶的電子郵件地址 (加上專屬 ID)。例如：my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901。如果服務帳戶未刪除，這個值會還原為 serviceAccount:{emailid}，且未刪除的服務帳戶會保留繫結中的角色。

  • deleted:group:{emailid}?uid={uniqueid}：代表最近刪除的 Google 群組的電子郵件地址 (加上專屬 ID)。例如，admins@example.com?uid=123456789012345678901。如果群組已復原，這個值會還原為 group:{emailid}，且復原的群組會保留繫結中的角色。

  • deleted:principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}：刪除員工身分集區中的單一身分。例如：deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value。
condition

object (Expr)

與此繫結相關聯的條件。

如果條件評估結果為 true，則這項繫結會套用至目前要求。

如果條件評估結果為 false，則這項繫結不適用於目前要求。不過，不同的角色繫結可能會將相同角色授予這個繫結中的一或多個主體。

如要瞭解哪些資源的 IAM 政策支援條件，請參閱 IAM 說明文件。

Expr

代表一般運算語言 (CEL) 語法的文字運算式。CEL 是一種類似 C 的運算式語言，如要瞭解 CEL 的語法和語意，請參閱 https://github.com/google/cel-spec。

範例 (比較)：

title: "Summary size limit"
description: "Determines if a summary is less than 100 chars"
expression: "document.summary.size() < 100"

範例 (相等)：

title: "Requestor is owner"
description: "Determines if requestor is the document owner"
expression: "document.owner == request.auth.claims.email"

範例 (邏輯)：

title: "Public documents"
description: "Determine whether the document should be publicly visible"
expression: "document.type != 'private' && document.type != 'internal'"

範例 (資料操控)：

title: "Notification string"
description: "Create a notification string with a timestamp."
expression: "'New message received at ' + string(document.create_time)"

運算式中可參照的確切變數和函式，取決於評估運算式的服務。詳情請參閱服務說明文件。

JSON 表示法 
{
  "expression": string,
  "title": string,
  "description": string,
  "location": string
}
欄位
expression

string

使用一般運算語言語法的運算式文字表示法。
title

string

(選用步驟) 運算式的標題，即描述其用途的簡短字串。這可用在允許輸入運算式的 UI 中。
description

string

(選用步驟) 運算式的說明。這是一段較長的文字，用於描述運算式。舉例來說，使用者在 UI 中將游標懸停在運算式上方時，即可顯示說明文字。
location

string

(選用步驟) 指出要提報錯誤的運算式所在位置，例如檔案名稱及檔案內的位置。

AuditConfig

指定服務的稽核設定。這類設定可判斷要記錄的權限類型，以及哪些身分識別不必記錄 (如適用)。AuditConfig 必須具有一或多個 AuditLogConfig。

如果 allServices 和特定服務都有 AuditConfigs，則該服務會使用這兩個 AuditConfig 的聯集：每個 AuditConfig 中指定的 log_types 都會啟用，而每個 AuditLogConfig 中的 exemptedMembers 則不啟用。

具有多個 AuditConfigs 的範例政策：

{
  "auditConfigs": [
    {
      "service": "allServices",
      "auditLogConfigs": [
        {
          "logType": "DATA_READ",
          "exemptedMembers": [
            "user:jose@example.com"
          ]
        },
        {
          "logType": "DATA_WRITE"
        },
        {
          "logType": "ADMIN_READ"
        }
      ]
    },
    {
      "service": "sampleservice.googleapis.com",
      "auditLogConfigs": [
        {
          "logType": "DATA_READ"
        },
        {
          "logType": "DATA_WRITE",
          "exemptedMembers": [
            "user:aliya@example.com"
          ]
        }
      ]
    }
  ]
}

針對 sampleservice，這項政策會啟用 DATA_READ、DATA_WRITE 和 ADMIN_READ 記錄功能。此外，該政策會將 jose@example.com 從 DATA_READ 記錄中排除，並將 aliya@example.com 從 DATA_WRITE 記錄中排除。

JSON 表示法 
{
  "service": string,
  "auditLogConfigs": [
    {
      object (AuditLogConfig)
    }
  ]
}
欄位
service

string

指定要啟用稽核記錄功能的服務，例如：storage.googleapis.com、cloudsql.googleapis.com。allServices 是涵蓋所有服務的特殊值。
auditLogConfigs[]

object (AuditLogConfig)

用於記錄各類型權限的設定。

AuditLogConfig

提供用於記錄權限類型的設定，例如：

{
  "auditLogConfigs": [
    {
      "logType": "DATA_READ",
      "exemptedMembers": [
        "user:jose@example.com"
      ]
    },
    {
      "logType": "DATA_WRITE"
    }
  ]
}

這樣可以啟用「DATA_READ」和「DATA_WRITE」記錄功能，同時避免 DATA_READ 記錄 jose@example.com。

JSON 表示法 
{
  "logType": enum (LogType),
  "exemptedMembers": [
    string
  ]
}
欄位
logType

enum (LogType)

此設定啟用的記錄類型。
exemptedMembers[]

string

指定不會導致記錄這類權限的身分識別，遵循 Binding.members 格式。

LogType

可設定記錄的有效權限類型清單。管理員寫入一律記錄，且無法設定。

列舉
LOG_TYPE_UNSPECIFIED 預設大小寫。一律不應為此值。
ADMIN_READ 管理員讀取，例如 CloudIAM getIamPolicy
DATA_WRITE 資料寫入，例如 CloudSQL Users create
DATA_READ 資料讀取，例如 CloudSQL Users list