IAM Conditions 的特性参考文档

本主题介绍了条件表达式中支持的特性。

支持的条件特性

下表总结了支持的特性,并指出了可识别每个特性的 Google Cloud 服务:

特性 用途摘要 支持的 Google Cloud 服务

访问权限级别特性

根据特定的访问权限级别管理访问权限。

访问权限级别是一种基于请求和请求者相关原始特性(例如源 IP 地址、设备特性、一天中的时间等)计算得出的特性。例如,onNetwork 访问权限级别可能要求发出请求的设备的 IP 地址源自特定的 IP 地址范围。访问权限级别由组织的管理员定义。

Identity-Aware Proxy

日期/时间特性

设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。

所有 Google Cloud 服务

目标 IP/端口特性

根据请求的目标 IP 地址和/或端口管理访问权限。例如,Compute Engine 虚拟机 (VM) 实例可能会公开一个外部 IP(如 10.0.0.2),但端口 22 可能仅会出于管理目的公开。

当前主要用于 Identity-Aware Proxy TCP 转发

Identity-Aware Proxy

转发规则特性

指定成员可以创建的转发规则的类型。例如,您可以允许成员为内部 Google Cloud 负载平衡器(用于处理源自 Google Cloud 网络的流量)创建转发规则,但不允许为外部 Google Cloud 负载平衡器(用于处理源自互联网的流量)创建转发规则。

  • Cloud Load Balancing
  • Cloud VPN
  • Compute Engine 协议转发
  • Traffic Director

资源特性

资源名称、资源类型和资源服务特性可让您授予对项目、文件夹或组织中某些资源(而非所有资源)的访问权限。

  • Cloud Key Management Service
  • Cloud Spanner
  • Cloud Storage
  • Compute Engine

网址路径/主机特性

根据请求的网址路径和/或主机管理访问权限。例如,某项条件可以指定 https://example.com 是可通过用户的常规网域访问的主应用,而 https://hr.example.com/admin 则用于访问仅人力资源管理员才有权访问的应用中的页面。

Identity-Aware Proxy

某些类型的 Google Cloud 资源不允许在其 IAM 政策中使用条件。不过,您可以在组织、文件夹或项目级层添加条件式角色绑定,其他资源将通过资源层次结构沿用这些角色绑定。有关详情,请参阅接受条件式角色绑定的资源

在组织、文件夹或项目级层使用特性时,请注意,如果您向某个服务发送了一条请求,而该服务无法识别条件中的某个特性,则该条件的计算结果将始终为 false。例如,因为 BigQuery 无法识别目标 IP/端口特性,所以对于 BigQuery,条件 destination.port == 21 的计算结果始终为 false

要避免此问题,请使用此页面上的资源特性来限制条件的范围。例如,对于除 Identity-Aware Proxy 之外的所有服务,条件 resource.service != "iap.googleapis.com" || destination.port == 21 的计算结果为 true;而对于 Identity-Aware Proxy,该条件会检查目标端口。

访问权限级别特性

借助访问权限级别特性,用户可以设置条件,规定只有在请求满足特定访问权限级别时才能为其授权。

访问权限级别特性派生自请求的特性(例如源 IP 地址、设备特性、一天中的时间等)。例如,名为 fullyTrusted 的访问权限级别可能会要求发出请求的设备归公司所有,并设置了屏幕锁定。onNetwork 访问权限级别可能要求发出请求的设备源自特定的 IP 地址范围。

如需详细了解访问权限级别,请参阅 Access Context Manager 文档。

Identity-Aware Proxy 中提供了此特性。

request.auth.access_levels 特性

特性变量 request.auth.access_levels
特性类型 字符串列表
支持的运算符 in
支持的操作数 字符串
讨论

变量 request.auth.access_levels 显示在 in 运算符右侧,其左侧显示代表已定义访问权限级别全名的字符串。

访问权限级别的全名采用以下名称格式:
"accessPolicies/<policyNumber>/accessLevels/<shortName>"

注意:访问权限级别字符串区分大小写,且必须与 Access Context Manager 中的配置完全匹配才能产生预期作用。例如,“accessPolicies/199923665455/accessLevels/CorpNet”是要在表达式中使用的有效字符串文本,而“accessPolicies/199923665455/accesslevels/CorpNet”无法产生预期作用。

示例

"accessPolicies/199923665455/accessLevels/CorpNet"
in request.auth.access_levels

日期/时间特性

日期/时间特性用于设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。

所有 Google Cloud 服务均支持此条件特性。

支持的基本函数和运算符

用于日期/时间特性的特性变量为 request.time,其类型为时间戳。您还可以将字符串转换为时间戳和时长类型。

支持的基本函数 类型 说明
date String --> Timestamp

函数:将字符串转换为时间戳。
参数:格式为 YYYY-MM-DD 的字符串,其中 YYYY 为年份,MM 为两位数的月份,DD 为两位数的日期。生成的时间戳包含指定日期和时间 00:00:00.000 UTC

示例

date("2020-02-01")
表示日期 2020-02-01 和时间 00:00:00.000 UTC 的时间戳。

duration String --> Duration

函数:将字符串转换为时长。
参数:包含秒数的字符串,后跟 s

示例

duration("90s")
表示 1.5 分钟的时长。

duration("2592000s")
表示 30 天的时长。

timestamp

String --> Timestamp

函数:将字符串转换为时间戳。
参数:遵循世界协调时间 (UTC) 格式 (RFC 3339) 的字符串。

示例

timestamp("1985-04-12T23:20:50.52Z")
这表示对 1985 年 4 月 12 日 23 时 20 分 50.52 秒(采用世界协调时间 (UTC))的时间戳转换。

timestamp("1996-12-19T16:39:57-08:00")
这表示对 1996 年 12 月 19 日 16 时 39 分 57 秒(与世界协调时间 (UTC) 的偏移量为 -08:00)的时间戳转换。请注意,此时间相当于采用世界协调时间 (UTC) 的 1996-12-20T00:39:57Z。此偏移量不能反映时区,例如,太平洋标准时间相对于世界协调时间 (UTC) 的偏移量在冬季为 -08:00,而在夏季由于采用夏令时,其偏移量变为 -07:00。

重要提示
字符串必须遵循世界协调时间 (UTC) 字符串的格式要求。任何不符合世界协调时间 (UTC) 格式的字符串都会导致 timestamp() 函数无法将字符串转换为时间戳值。因此,使用 timestamp() 对表达式进行条件评估会导致授权失败。

<, <=, >, >=

(Timestamp, Timestamp) --> bool

函数:与时间戳类型的常规比较。

示例

request.time < timestamp("2018-04-12T00:00:00.00Z")
request.time <= timestamp("2018-04-12T00:00:00.00Z")
request.time > timestamp("2018-04-12T00:00:00.00Z")
request.time >= timestamp("2018-04-12T00:00:00.00Z")
这些表达式会将请求时间与指定时间戳(示例中为世界协调时间 (UTC) 的 2018 年 4 月 12 日)进行比较。通常用于设置角色授予的“开始时间”或“到期时间”条件。

注意:由于时间精确到毫秒,包含等于和不等于比较(==!=)的意义不大。

+- (Timestamp, Duration) --> Timestamp

函数:在时间戳的基础上加上或减去时长。

示例

timestamp("2018-04-12T14:30:00.00Z") + duration("1800s")
查找格林尼治标准时间 2018 年 4 月 12 日 14:30:00 之后 30 分钟内的时间戳。

timestamp("2018-04-12T14:30:00.00Z") - duration("5184000s")
查找格林尼治标准时间 2018 年 4 月 12 日 14:30:00 之前 60 天内的时间戳。

支持的高级函数和运算符

用于日期/时间特性的特性变量为 request.time,类型为时间戳。

支持的高级函数 类型 说明

<, <=, >, >=, ==, !=

(int, int) --> bool

函数:对 int 类型的值执行常规比较。

讨论
这组整数比较运算符主要供带有时间戳函数的其余“高级函数”使用。所有这些函数(请参见此表其余部分的定义)将时间戳值的特定部分转换为 int 类型。我们还提供了各种高级函数的示例,展示了常见用法建议。

getDate, getDayOfMonth, getDayOfWeek, getDayOfYear

Timestamp.() --> int

Timestamp.(string) --> int

函数
getDate:根据时间戳值获取一个月中的某天(从 1 开始编制索引)。这种索引编制方式的含义是,一个月的第一天是 1。

getDayOfMonth:根据时间戳值获取一个月中的某天(从 0 开始编制索引)。这种索引编制方式的含义是,一个月的第一天是 0。

getDayOfWeek:根据时间戳值(星期日索引为 0)获取一周中的某天。这种索引编制方式的含义是,星期天(0)、星期一(1)、...、星期六(6)。

getDayOfYear:根据时间戳值获取一年中的某天(从 0 开始编制索引)。这种索引编制方式的含义是,一年的第一天是 0。

参数
字符串表示时区:根据该时区的日期进行转换。注意:如果未指定时区,将根据世界协调时间 (UTC) 日期进行转换。

如需详细了解有效的时区字符串,请参阅支持的时区值

示例

request.time.getDayOfWeek() > 0 && request.time.getDayOfWeek() < 6
如果传入请求是在星期一到星期五之间(采用世界协调时间 (UTC) 时间)发送的,则此表达式的计算结果为 true。

示例

request.time.getDayOfWeek("Europe/Berlin") > 0 && request.time.getDayOfWeek(Europe/Berlin") < 6
如果收到的请求是在星期一到星期五(采用柏林时区)之间发送的,则此表达式的计算结果为 true。

示例

request.time.getDayOfYear("America/Los_Angeles") >= 0 && request.time.getDayOfYear("America/Los_Angeles") < 5
如果传入请求在一年的前 5 天(采用洛杉矶时区)内发送的,则此表达式的计算结果为 true。

getFullYear

Timestamp.() --> int

Timestamp.(string) --> int

函数:获取日期的年份。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

示例

request.time.getFullYear("America/Los_Angeles") == 2018
如果传入请求是在 2018 年(采用洛杉矶时区)发送的,则此表达式的计算结果为 true。

示例

request.time.getFullYear() < 2020
如果传入请求是在 2019 年年底(采用世界协调时间 (UTC))之前发送的,则此表达式的计算结果为 true。

getHours

Timestamp.() --> int

Timestamp.(string) --> int

函数:获取日期的小时数;值介于 0 到 23 之间。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

示例

request.time.getHours("Europe/Berlin") >= 9 && request.time.getHours("Europe/Berlin") <= 17
此表达式指定了工作时间条件。如果相应请求在上午 9 点至下午 5 点(采用柏林时区)之间发送,则此表达式的计算结果为 true。

注意

getHours()getDayofWeek() 结合使用可用于设置法定工作时间条件,例如出于符合司法管辖区要求的目的。

getMilliseconds

Timestamp.() --> int

Timestamp.(string) --> int

函数:根据时间戳获取一秒中的毫秒数;值介于 0 到 999 之间。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

注意

鉴于语义上的有限用法,此函数用处不大。

getMinutes

Timestamp.() --> int

Timestamp.(string) --> int

函数:根据时间戳获取一小时中的分钟数;值介于 0 到 59 之间。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

注意

鉴于语义上的有限用法,此函数用处不大。

getMonth

Timestamp.() --> int

Timestamp.(string) --> int

函数:根据时间戳获取一年中的月数;值介于 0 到 11 之间。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

示例

request.time.getMonth("America/Los_Angeles") == 3
如果传入请求是在 4 月份(采用洛杉矶时区)发送的,则此表达式的计算结果为 true。

getSeconds

Timestamp.() --> int

Timestamp.(string) --> int

函数:根据时间戳获取一分钟中的秒数;值介于 0 到 59 之间。

参数
版本 1:无参数;以世界协调时间 (UTC) 日期为依据。
版本 2:时区字符串;以相应时区的日期为依据。

如需详细了解有效的时区字符串,请参阅支持的时区值

注意

鉴于语义上的有限用法,此函数用处不大。

目标 IP/端口特性

目标 IP/端口特性可让用户根据请求的目标 IP 地址和/或端口管理访问权限。例如,Compute Engine 虚拟机实例可能会在端口 3001 上公开用于常规用途的外部 IP 地址 10.0.0.1,但 IP 地址 10.0.0.2 和端口 22 仅为管理用途而公开。

如需详细了解 TCP 转发,请参阅 Identity-Aware Proxy 文档。

Identity-Aware Proxy 支持此特性。

destination.ip 特性

特性变量 destination.ip
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串
讨论

变量 destination.ip 应是一个字符串,表示 IPv4 格式的 IP 地址。

注意startsWith(<prefix string of IP>) 函数和 endsWith(<suffix string of IP>) 函数不应与 destination.ip 特性一起使用。虽然设置 destination.ip.startsWith(<prefix string of IP>) 之类的条件不会在执行 setIamPolicy 操作时造成语法错误,但由于会出现意外结果,我们不建议如此设置。对 CIDR 执行 IP 地址范围检查时,不建议在 IP 字符串上进行前缀匹配。

示例

destination.ip == "10.0.0.1"

destination.ip != "10.0.0.1"

destination.port 特性

特性变量 destination.port
特性类型 整数
支持的运算符 ==, !=, <, <=, >, >=
支持的操作数 整数
讨论

变量 destination.port 应是表示 TCP 端口号的整数。

示例

destination.port == 21

destination.port < 3001

转发规则特性

借助转发规则特性,您可以指定成员可以创建的转发规则的类型。例如,您可以允许成员为内部 Google Cloud 负载平衡器(用于处理源自 Google Cloud 网络的流量)创建转发规则,但不允许为外部 Google Cloud 负载平衡器(用于处理源自互联网的流量)创建转发规则。

对于 Cloud Load Balancing,转发规则特性不会影响创建 Google Cloud 负载平衡器的其他组件(例如后端服务、目标代理、运行状况检查和网址映射)的能力。

以下 Google Cloud 服务支持转发规则特性:

  • Cloud Load Balancing
  • Cloud VPN
  • Compute Engine 协议转发
  • Traffic Director

支持的函数

支持的函数 类型 说明
compute.isForwardingRuleCreationOperation() () --> bool

函数:检查请求是否正在创建转发规则

示例:查看 compute.matchLoadBalancingSchemes() 的示例。

compute.matchLoadBalancingSchemes() Array.(string)--> bool

函数:检查请求是否会影响指定类型的负载平衡方案。如需查找每种负载平衡方案的标识符以及详细了解每种方案,请参阅在 Google Cloud 负载平衡器上使用 IAM Conditions

参数:字符串数组

示例


!compute.isForwardingRuleCreationOperation() || (
  compute.isForwardingRuleCreationOperation() &&
  compute.matchLoadBalancingSchemes([
    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
  ]))
)
  • 如果请求不是创建转发规则,则将该角色授予该成员。
  • 如果请求是创建转发规则,则仅在转发规则影响 INTERNALINTERNAL_MANAGEDINTERNAL_SELF_MANAGED 负载平衡方案时授予角色。

资源特性

资源名称、资源类型和资源服务特性通常用于更改角色绑定提供的访问授权的范围。如果角色包含适用于不同资源特定特性的权限,则可以使用基于资源的条件,授予角色权限中针对特定类型或特定服务的一部分权限。

以下 Google Cloud 服务支持资源特性:

  • Cloud Spanner
  • Cloud Storage
  • Compute Engine
  • Identity-Aware Proxy
  • Cloud Key Management Service
  • Resource Manager(仅限资源类型和资源服务)

如需详细了解可用于各项服务的资源特性,请参阅 IAM Conditions 的资源特性

从资源名称中提取值

您可以使用 extract() 函数从资源名称中提取值。 此函数允许条件表达式引用资源名称的任意部分。

要提取值,请使用 extract() 函数并提供提取模板,该模板可指定要提取的资源名称中的某个片段。例如,您可以使用模板 projects/{project}/ 从 Compute Engine 虚拟机实例的资源名称中提取项目 ID。

提取模板包含以下组成部分:

  • 括号内的标识符,用于标识要提取的子字符串。请选择一个有意义的简短标识符,明确指出要提取的值。您可以使用从 AZ 的大写和小写字母、数字、短划线 (-)、和下划线 (_)。

    在模板 projects/{project}/ 中,标识符为 project

  • (可选)前缀,它必须出现在要提取的子字符串之前。

    在模板 projects/{project}/ 中,前缀为 projects/

  • (可选)后缀,必须出现在要提取的子字符串之后。

    在模板 projects/{project}/ 中,后缀为 /

根据提取模板是否带有前缀、后缀或者两者兼有,extract() 函数会返回不同的值:

有前缀 有后缀 提取的值
资源的完整名称
第一处出现的前缀后的字符,如果前缀后面没有字符,则为空字符串
第一处出现的后缀前的字符,如果后缀前面没有字符,则为空字符串
第一处出现的前缀与其后第一处出现的后缀之间的字符,如果该前缀与该后缀之间没有字符,则为空字符串

如果您指定的前缀或后缀未出现在资源名称中,或后缀仅出现在前缀之前,则 extract() 函数会返回 null

以下示例展示了几个不同提取模板的输出结果。在以下示例中,资源是名为 projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876 的 Cloud Storage 对象:

提取模板 输出
/order_date={date}/ 2019-11-03
buckets/{name}/ acme-orders-aaa
/orders/{empty}order_date 空字符串
{start}/data_lake projects/_/buckets/acme-orders-aaa
orders/{end} order_date=2019-11-03/aef87g87ae0876
{all} projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876
/orders/{none}/order_date= null
/orders/order_date=2019-11-03/{id}/data_lake null

您还可以使用此页面上的日期/时间函数和运算符,将提取的值转换为时间戳。有关示例,请参阅配置基于资源的访问权限

resource.name 特性

特性变量 resource.name
特性类型 字符串
支持的运算符 startsWith()endsWith()extract()==!=
支持的操作数

字符串

每种资源类型都为资源名称使用一种特定格式。如需查看这些格式的列表,请参阅资源名称格式

讨论

resource.name 包含请求中目标资源的相关资源名称。相关资源名称是不带正斜线 (/) 的 URI 路径。

startsWith() 函数接受前缀字符串字面量,并针对 resource.name 执行计算。

endsWith() 函数接受后缀字符串字面量,并针对 resource.name 执行计算。

extract() 函数使用提取模板来提取 resource.name 的子字符串。如需了解详情,请参见本页面上的从资源名称中提取值

==!= 运算符用于与完整的 resource.name 或者 resource.name 的提取部分进行比较。

示例

示例 1(对于 Compute Engine 虚拟机实例):


resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod-")

示例 2(对于 Cloud Storage 存储分区):


resource.name.startsWith("projects/_/buckets/my_bucket/objects/test-object-")

示例 3(对于 Cloud Storage 对象):


resource.name.endsWith(".jpg")

示例 4(对于多种资源类型):


resource.name.extract("projects/{project}/")

示例 5(对于 Cloud Storage 存储分区):


resource.name != "projects/_/buckets/secret-bucket-123"

resource.service 特性

特性变量 resource.service
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串


如需查看所有支持的资源服务字符串字面量的列表,请参阅 IAM Conditions 的资源特性

讨论 变量 resource.service(如使用)用于执行相等性或不等性比较。

注意.startsWith(<prefix string>).endsWith(<suffix string>) 函数不应与 resource.service 特性一起使用,否则会出现意外计算结果,出于此原因,不建议您将这些函数与该特性一起使用。

示例

示例 1:


resource.service == "compute.googleapis.com"

resource.type 特性

特性变量 resource.type
特性类型 字符串
支持的运算符 ==, !=
支持的操作数 字符串


如需查看所有支持的资源类型字符串字面量的列表,请参阅 IAM Conditions 的资源特性

讨论 变量 resource.type(如使用)用于执行相等性或不等性比较。

注意.startsWith(<prefix string>).endsWith(<suffix string>) 函数不应与 resource.type 特性一起使用,否则会出现意外计算结果,出于此原因,不建议您将这些函数与该特性一起使用。

示例

示例 1:


resource.type != "compute.googleapis.com/Image"

示例 2:


(resource.type == "compute.googleapis.com/Image" ||
resource.type == "compute.googleapis.com/Disk")

网址路径/主机特性

通过网址路径/主机特性,用户可以根据请求的网址路径和/或主机来管理访问权限。例如,某项条件可以指定 https://example.com 是可供用户的常规网域访问的主应用,而 https://hr.example.com/admin 用于访问应用中只有人力资源管理员才能访问的部分下的某个页面。

Identity-Aware Proxy 支持此特性。

request.path 特性

特性变量 request.path
特性类型 字符串
支持的运算符 ==, startsWith(), endsWith()
支持的操作数/参数
  • 字符串:==
  • 常量前缀字符串:startsWith()
  • 常量后缀字符串:endsWith()
讨论 注意:我们不建议使用 != 运算符。 建议您不要使用下面这样的否定比较:

request.path != "/admin"
而是使用前缀匹配,例如:

! request.path.startsWith("/admin")
这样,以“/admin”为父级路径的网址路径(例如“/admin/payroll/”)就会受到保护,不会出现意外访问。
示例

示例 1:


request.path == "/admin"

request.path == "/admin/payroll"

在上述两个示例中的相等性 (==) 比较中使用的字符串应根据网址路径标准进行格式设置。

示例 2:


request.path.startsWith("/admin")

此函数中使用表示网址路径前缀的字符串。

示例 3:


request.path.endsWith("/payroll.js")

此函数中使用表示网址路径后缀的字符串。

request.host 特性

特性变量 request.host
特性类型 字符串
支持的运算符 ==, endsWith()
支持的操作数/参数
  • 字符串:==
  • 常量后缀字符串:endsWith()
讨论 .startsWith(<prefix string>) 函数不应与 request.host 特性一起使用。虽然设置 request.host.startsWith(<prefix string>) 之类的条件不会在执行 setIamPolicy 操作时造成语法错误,但由于会出现意外结果,我们不建议如此设置。出于同样的原因,也不建议您使用 !=
示例

示例 1:


request.host == "www.example.com"

request.host == "hr.example.com"

在上述两个示例中的相等性 (==) 比较中使用的字符串应根据网站主机名的网址字符串标准进行格式设置。

示例 2:


request.host.endsWith("example.com")

表示网站主机名后缀的字符串。