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)
    }
  ],
  "rules": [
    {
      object (Rule)
    }
  ],
  "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 向 user:alice@example.com 授予了 50 个不同的角色且没有向任何其他主账号授予角色，那么您最多还可以向 Policy 中的 bindings 添加 1,450 个主账号。
auditConfigs[]

object (AuditConfig)

指定此政策的 Cloud Audit Logging 配置。
rules[]

object (Rule)

如果指定了多条规则，则按以下方式应用规则：- 始终应用所有匹配的 LOG 规则。- 如果有任何 DENY/DENY_WITH_LOG 规则匹配，权限会被拒绝。如果有一条或多条匹配规则需要日志记录，则将应用日志记录。- 否则，如果任何 ALLOW/ALLOW_WITH_LOG 规则匹配，则授予权限。如果有一条或多条匹配规则需要日志记录，则将应用日志记录。- 否则，如果未应用任何规则，则系统会拒绝授予权限。
etag

string (bytes format)

etag 用于乐观并发控制，可帮助防止同时对政策进行的更新相互覆盖。强烈建议系统在“读取-修改-写入”周期中使用 etag 来执行政策更新以避免冲突：返回 etag 来响应 getIamPolicy，系统应将该 etag 放入对 setIamPolicy 的请求中，以确保其更改将应用于同一版本的政策。

重要提示：如果您使用 IAM 条件，则必须在调用 setIamPolicy 时包含 etag 字段。如果您省略此字段，则 IAM 允许您使用版本 1 政策覆盖版本 3 政策，而且版本 3 政策中的所有条件都会丢失。

base64 编码的字符串。

绑定

将 members 或主账号与 role 关联。

JSON 表示法 
{
  "role": string,
  "members": [
    string
  ],
  "condition": {
    object (Expr)
  },
  "bindingId": string
}
字段
role

string

分配给 members 或主账号列表的角色。例如 roles/viewer、roles/editor 或 roles/owner。

如需简要了解 IAM 角色和权限，请参阅 IAM 文档。如需查看可用的预定义角色列表，请点击此处。
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 服务账号的标识符。例如 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/{projectNumber}/locations/global/workloadIdentityPools/{pool_id}/subject/{subject_attribute_value}：工作负载身份池中的单个身份。

  • principalSet://iam.googleapis.com/projects/{projectNumber}/locations/global/workloadIdentityPools/{pool_id}/group/{groupId}：工作负载身份池组。

  • principalSet://iam.googleapis.com/projects/{projectNumber}/locations/global/workloadIdentityPools/{pool_id}/attribute.{attribute_name}/{attribute_value}：工作负载身份池中具有特定特性的所有身份。

  • principalSet://iam.googleapis.com/projects/{projectNumber}/locations/global/workloadIdentityPools/{pool_id}/*：工作负载身份池中的所有身份。

  • deleted:user:{emailid}?uid={uniqueid}：表示最近被删除的用户的电子邮件地址（以及唯一标识符）。例如 alice@example.com?uid=123456789012345678901。如果用户已恢复，则此值会恢复为 user:{emailid}，而且恢复的用户将保留绑定中的角色。

  • deleted:serviceAccount:{emailid}?uid={uniqueid}：表示最近被删除的服务账号的电子邮件地址（以及唯一标识符）。例如 my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901。如果恢复删除的服务账号，则此值会还原为 serviceAccount:{emailid}，而且删除的服务账号在恢复后将保留绑定中的角色。

  • deleted:group:{emailid}?uid={uniqueid}：表示最近被删除的 Google 群组的电子邮件地址（以及唯一标识符）。例如 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 文档。
bindingId

string

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

可选。表达式的标题，即说明表达式用途的短字符串。该标题可用于允许输入表达式的内容（例如界面）中。
description

string

可选。表达式的说明。该说明是描述表达式的较长文本，例如在界面中将鼠标悬停在表达式上时显示的文本。
location

string

可选。指示用于错误报告的表达式位置的字符串，例如文件名和文件中的位置。

AuditConfig

指定服务的审核配置。该配置决定要记录哪些权限类型，以及不记录哪些身份（若有）。AuditConfig 必须具有一个或多个 AuditLogConfig。

如果 allServices 和特定服务都具有 AuditConfig，则系统会将两个 AuditConfig 的并集用于该服务：每个 AuditConfig 中指定的 log_types 将被启用，而每个 AuditLogConfig 中的 exempted_members 将被排除。

具有多个 AuditConfig 的示例政策如下所示：

{
  "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 活动启用日志记录。它还会从 DATA_READ 日志记录中排除 jose@example.com，从 DATA_WRITE 日志记录中排除 aliya@example.com。

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 活动启用日志记录，同时从日志记录中排除 jose@example.com 的 DATA_READ 活动。

JSON 表示法 
{
  "logType": enum (LogType),
  "exemptedMembers": [
    string
  ],
  "ignoreChildExemptions": boolean
}
字段
logType

enum (LogType)

此配置启用的日志类型。
exemptedMembers[]

string

指定不会导致对这种权限进行日志记录的身份。遵循与 Binding.members 相同的格式。
ignoreChildExemptions

boolean

LogType

可以为其配置日志记录的有效权限类型的列表。管理员写入始终予以记录，且不可配置。

枚举
LOG_TYPE_UNSPECIFIED 默认设置。切勿使用此值。
ADMIN_READ 管理员读取。示例：CloudIAM getIamPolicy
DATA_WRITE 数据写入。示例：CloudSQL Users create
DATA_READ 数据读取。示例：CloudSQL Users list

规则

要在 Policy 中应用的规则。

JSON 表示法 
{
  "description": string,
  "permissions": [
    string
  ],
  "action": enum (Action),
  "in": [
    string
  ],
  "notIn": [
    string
  ],
  "conditions": [
    {
      object (Condition)
    }
  ],
  "logConfig": [
    {
      object (LogConfig)
    }
  ]
}
字段
description

string

直观易懂的规则说明。
permissions[]

string

权限是格式为“..”的字符串（例如，“storage.buckets.list”）。值“*”会匹配所有权限，且“*”的动词部分（例如，“storage.buckets.*”）匹配所有动词。
action

enum (Action)

需要
in[]

string

如果指定了一个或多个“in”子句，则只要 PRINCIPAL/AUTHORITY_SELECTOR 位于至少一个条目中，规则就匹配。
notIn[]

string

如果指定了一个或多个“notIn”子句，则当 PRINCIPAL/AUTHORITY_SELECTOR 不在任何条目中时，规则匹配。
conditions[]

object (Condition)

必须满足的其他限制。必须满足所有条件才能匹配规则。
logConfig[]

object (LogConfig)

针对与 LOG 操作匹配的任何条目，将配置返回给 CheckPolicy 的调用方。

操作

规则操作类型。

枚举
NO_ACTION 默认为无操作。
ALLOW 匹配“条目”可授予访问权限。
ALLOW_WITH_LOG 匹配“条目”会授予访问权限，且调用方承诺根据返回的 log_configs 记录请求。
DENY 若与“条目”匹配，则拒绝访问。
DENY_WITH_LOG 匹配“条目”可拒绝访问，且调用方承诺根据返回的 log_configs 记录请求。
LOG 匹配的“条目”会告知 IAM。检查调用方以生成日志。

条件

要满足的条件。

JSON 表示法 
{
  "op": enum (Operator),
  "values": [
    string
  ],

  // Union field Subject can be only one of the following:
  "iam": enum (Attr),
  "sys": enum (Attr),
  "svc": string
  // End of list of possible types for union field Subject.
}
字段
op

enum (Operator)

用于应用主题的运算符。
values[]

string

条件的对象。
联合字段 Subject。条件主题。Subject 只能是下列其中一项：
iam

enum (Attr)

由 IAM 系统提供的可信属性。
sys

enum (Attr)

由拥有资源并使用 IAM 系统进行访问权限控制的任何服务提供的可信属性。
svc

string

服务释放的可信属性。

Attr

属性类型。

枚举
NO_ATTR 默认非属性。
AUTHORITY 主账号或（如果存在）授权方选择器。
ATTRIBUTION 主账号（即使存在授权方选择器），该选择器只能用于归因，不能用于授权。
SECURITY_REALM IAMContext (go/security-realms) 中的任何安全领域。与 IN 一起使用时，条件指示“请求的任何领域都与其中一个给定值匹配；对于 NOT_IN，‘任何领域都与任何给定值都不匹配”。请注意，值可以是：-“self:campus”（即在同一园区中的客户端）-“self:metro”（即位于同一都市圈的客户端）-“self:cloud-region”（即，允许来自同一云区域的客户端的连接）-“self:prodi”中的连接（即来自其所在区域的客户端），“self:prodi”中的“allowi”连接（来自其所在区域的客户端）（即来自同一区域的客户端）如需了解详情，请访问 go/security-realms-glossary#guardian。）-“self”[已弃用]（即允许来自同一安全领域的客户端的连接，目前该安全领域并不保证与校园规模的连接）- 领域（例如'campus-abc') - 领域组（例如，“realms-for-borg-cell-xx”请参阅：go/realm-groups) 匹配由 RealmAclRep 对象 (go/realm-acl-howto) 执行的领域群组成员资格检查确定。不允许基于某个领域的不存在来授予访问权限，因此领域条件只能在“积极的”上下文（例如ALLOW/IN 或 DENY/NOT_IN）。
APPROVER 已授权此请求的审批人（不同于请求者）。与 IN 搭配使用时，该条件表示与请求关联的某个审批人与指定的主账号匹配，或者是指定群组的成员。审批人只能授予额外的访问权限，因此只能用于绝对肯定的上下文（例如 ALLOW/IN 或 DENY/NOT_IN）。
JUSTIFICATION_TYPE

此请求提供了哪些类型的理由。字符串值应与 security.credentials.JustificationType 中的枚举名称匹配，例如“MANUAL_STRING”。不允许根据缺少理由授予访问权限，因此只能在“肯定”上下文（例如ALLOW/IN 或 DENY/NOT_IN）。

多个理由（例如 Buganizer ID 和手动输入的原因）是正常且受支持的。
CREDENTIALS_TYPE 随此请求提供的凭据类型。字符串值应与 security_loas_l2.CredentialsType 中的枚举名称相匹配，目前仅支持 CREDS_TYPE_EMERGENCY。不允许根据缺少凭据类型来授予访问权限，因此只能在“肯定”的上下文（例如ALLOW/IN 或 DENY/NOT_IN）。
CREDS_ASSERTION

实验性 -- 请勿使用。

这些条件只能在“积极”的上下文中使用（例如，ALLOW/IN 或 DENY/NOT_IN）。

Attr

属性类型。

枚举
NO_ATTR 默认非属性类型
REGION 资源的区域
SERVICE 服务名称
NAME 资源名称
IP 调用方的 IP 地址

运算符

条件运算符类型。

枚举
NO_OP 默认空操作。
EQUALS 已弃用。请改用 IN。
NOT_EQUALS 已弃用。请改用 NOT_IN。
IN 如果主题（或者它的任何元素，如果是一个集）与提供的任何值匹配，则条件为 true。
NOT_IN 如果主题（或者它的每个元素，如果是一个集）与提供的值都不匹配，则条件为 true。
DISCHARGED 正文已清退

LogConfig

指定调用方必须写入的日志类型

JSON 表示法 
{

  // Union field type can be only one of the following:
  "counter": {
    object (CounterOptions)
  },
  "dataAccess": {
    object (DataAccessOptions)
  },
  "cloudAudit": {
    object (CloudAuditOptions)
  }
  // End of list of possible types for union field type.
}
字段
联合字段 type。必须设置 type 只能是下列其中一项：
counter

object (CounterOptions)

计数器选项。
dataAccess

object (DataAccessOptions)

数据访问选项。
cloudAudit

object (CloudAuditOptions)

Cloud 审核选项。

CounterOptions

使用指定的指标和字段名称递增 streamz 计数器。

指标名称应以“/”开头，通常只能使用小写字母，并以“_count”结尾。字段名称不应包含初始斜杠。实际导出的指标名称会带有“/iam/policy”前缀。

字段名称对应于 IAM 请求参数，字段值是它们各自的值。

支持的字段名称：-“authority”，如果存在 IAMContext.token，则为“[token]”，否则为 IAMContext.authority_selector 的值（如果存在），否则为 IAMContext.principal 的表示法；或者 -“iamPrincipal”，表示 IAMContext.（即使存在令牌或授权方选择器），或者 - ""（空字符串），导致出现计数器字段。

示例：计数器 { metric: "/debug_access_count" field: "iamPrincipal" } ==> 递增计数器 /iam/policy/debug_access_count {iamPrincipal=[IAMContext.principal 的值]}

JSON 表示法 
{
  "metric": string,
  "field": string,
  "customFields": [
    {
      object (CustomField)
    }
  ]
}
字段
metric

string

要更新的指标。
field

string

要归因的字段值。
customFields[]

object (CustomField)

自定义字段。

CustomField

自定义字段。这些可用于创建具有任意字段/值对的计数器。请参阅：go/rpcsp-custom-fields。

JSON 表示法 
{
  "name": string,
  "value": string
}
字段
name

string

Name 为字段名称。
value

string

value 为字段值。与 CounterOptions.field 相比，此处的值是一个不是从 IAMContext 派生的常量，这一点很重要。

DataAccessOptions

写入数据访问 (Gin) 日志

JSON 表示法 
{
  "logMode": enum (LogMode),
  "isDirectAuth": boolean
}
字段
logMode

enum (LogMode)
isDirectAuth

boolean

表示访问权限是由常规授权政策授予的

LogMode

指定 Gin 日志记录的客户端行为。

枚举
LOG_MODE_UNSPECIFIED 在授权检查完成后，客户端无需立即写入部分 Gin 日志。如果客户端选择写入一个函数但失败了，客户端可能会应急开启（允许操作继续）或应急关闭（作为 DENY 结果处理）。
LOG_FAIL_CLOSED

只有在成功记录到 Gin 中后，才能执行此授权检查的应用操作。例如，授权库可通过以下方式满足此义务：在授权检查时发送部分日志条目，并且仅在成功时向应用返回 ALLOW。

如果匹配规则包含此指令，但客户端未指明它会遵循此类要求，则 IAM 检查将通过设置 CheckPolicyResponse.success=false 导致授权失败。

CloudAuditOptions

写入 Cloud Audit Logs

JSON 表示法 
{
  "logName": enum (LogName),
  "authorizationLoggingOptions": {
    object (AuthorizationLoggingOptions)
  },
  "permissionType": enum (PermissionType)
}
字段
logName

enum (LogName)

要在 Cloud Audit Record 中填充的 logName。
authorizationLoggingOptions

object (AuthorizationLoggingOptions)

Cloud Audit Logging 流水线使用的信息。完成向 PermissionType 的迁移后，将废弃此项 (b/201806118)。
permissionType

enum (PermissionType)

与权限关联的类型。

LogName

日志名称的枚举。

枚举
UNSPECIFIED_LOG_NAME 默认值。不应使用。
ADMIN_ACTIVITY 对应于“cloudaudit.googleapis.com/activity”
DATA_ACCESS 对应于“cloudaudit.googleapis.com/dataAccess”

AuthorizationLoggingOptions

Cloud Audit Logging 使用的授权相关信息。

JSON 表示法 
{
  "permissionType": enum (PermissionType)
}
字段
permissionType

enum (PermissionType)

已检查的权限的类型。

PermissionType

可检查的有效权限类型的列表。

枚举
PERMISSION_TYPE_UNSPECIFIED 默认值。不应使用。
ADMIN_READ 读取管理员（元）数据。
ADMIN_WRITE 管理（元数据）数据的写入。
DATA_READ 读取标准数据。
DATA_WRITE 标准数据的写入。

PermissionType

可检查的有效权限类型的列表。

枚举
PERMISSION_TYPE_UNSPECIFIED 默认值。不应使用。
ADMIN_READ 控制读取资源配置或元数据的权限。
ADMIN_WRITE 用于控制资源配置或元数据修改的权限。
DATA_READ 用于控制读取用户提供的数据的权限。
DATA_WRITE 用于控制写入用户提供的数据的权限。