本主题介绍了条件表达式中支持的特性。
支持的条件特性
以下几个部分总结了支持的特性,并指出了可识别每个特性的 Google Cloud 服务。
资源特性
以下特性与作为请求主体的资源有关。
特性 | 用途摘要 | 支持的 Google Cloud 服务 |
---|---|---|
资源服务特性 | 根据正在使用的 Google Cloud 服务管理访问权限。 |
|
资源类型特性 | 根据资源类型管理访问权限。 | |
资源名称特性 | 根据资源名称管理访问权限。 | |
资源标记 | 根据关联到资源的标记管理访问权限。 | 所有 Google Cloud 服务 |
如需详细了解资源特性,请参阅本页面上的资源特性。
请求特性
以下特性与请求的详细信息有关。
特性 | 用途摘要 | 支持的 Google Cloud 服务 |
---|---|---|
根据特定的访问权限级别管理访问权限。 访问权限级别是一种基于请求和请求者相关原始特性(例如源 IP 地址、设备特性、一天中的时间等)计算得出的特性。例如, |
Identity-Aware Proxy |
|
根据特定 Google Cloud API 或服务提供的数据管理访问权限。 |
|
|
设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。 |
所有 Google Cloud 服务 |
|
根据请求的目标 IP 地址和/或端口管理访问权限。例如,Compute Engine 虚拟机 (VM) 实例可能会公开一个外部 IP 地址(如 当前主要用于 Identity-Aware Proxy TCP 转发。 |
Identity-Aware Proxy |
|
指定成员可以创建的转发规则的类型。例如,您可以允许成员为内部 Google Cloud 负载平衡器(用于处理源自 Google Cloud 网络的流量)创建转发规则,但不允许为外部 Google Cloud 负载平衡器(用于处理源自互联网的流量)创建转发规则。 |
|
|
根据请求的网址路径和/或主机管理访问权限。例如,某项条件可以指定 |
Identity-Aware Proxy |
如需详细了解请求特性,请参阅本页面上的请求特性。
支持继承条件
某些类型的 Google Cloud 资源不允许在其 IAM 政策中使用条件。不过,您可以在组织、文件夹或项目级层添加条件式角色绑定,其他资源将通过资源层次结构沿用这些角色绑定。如需了解详情,请参阅接受条件式角色绑定的资源。
在组织、文件夹或项目级使用特性时,请注意,大多数特性仅适用于特定资源类型。从 2021 年 2 月 26 日开始,如果条件的一部分使用的特性不可用,则系统绝不会将该部分条件解释为授予访问权限。例如,条件 destination.port == 21
绝不会授予任何 BigQuery 资源的访问权限,因为 BigQuery 资源不提供目标 IP 地址/端口特性。
要避免此问题,请使用本页面介绍的资源类型和资源服务特性来限制条件的范围。例如,对于除 Identity-Aware Proxy 隧道实例之外的所有资源类型,以下条件的计算结果为 true
;而对于 Identity-Aware Proxy 隧道实例,该条件会检查目标端口:
resource.type != 'iap.googleapis.com/TunnelInstance' ||
destination.port == 21
您不必限制用于检查关联到资源的标记的条件范围。当某个条件检查标记键和值时,无法检查任何其他特性,包括资源类型和资源服务。
资源特性
资源服务、资源类型和资源名称特性通常用于更改角色绑定提供的访问授权的范围。如果角色包含适用于不同资源特定特性的权限,则可以使用基于资源的条件,授予角色权限中针对特定类型或特定服务的一部分权限。
resource.service
特性
借助 resource.service
特性,您可以根据正在使用的 Google Cloud 服务设置条件。例如,您可以设置条件,限制用户访问使用 cloudresourcemanager.googleapis.com
服务的资源。
特性变量 | resource.service |
---|---|
特性类型 | 字符串 |
支持的运算符 | ==, != |
支持的操作数 | 字符串
|
讨论 | 变量 resource.service (如使用)用于执行相等性或不等性比较。
注意: |
示例 |
示例 1: resource.service == "compute.googleapis.com" |
支持的服务 |
|
resource.type
特性
借助 resource.type
特性,您可以根据资源类型设置条件。例如,您可以设置条件,限制用户访问 storage.googleapis.com/Object
类型的资源。
如果您的条件使用 resource.name
特性,我们强烈建议您使用 resource.type
特性来控制条件适用的资源类型。如需了解详情,请参阅本页面上的 resource.name
特性。
特性变量 | resource.type |
||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
特性类型 | 字符串 | ||||||||||||||||||
支持的运算符 | ==, != |
||||||||||||||||||
支持的操作数 | 字符串
|
||||||||||||||||||
讨论 | 变量 resource.type (如使用)用于执行相等性或不等性比较。
注意: |
||||||||||||||||||
示例 |
示例 1: resource.type != "compute.googleapis.com/Image" 示例 2: (resource.type == "compute.googleapis.com/Image" || |
||||||||||||||||||
支持的资源类型 |
1 Cloud Key Management Service 将此资源类型用作密钥环资源的父级。 |
resource.name
特性
借助 resource.name
特性,您可以根据资源名称的全部或部分内容设置条件。
resource.name
特性仅适用于下表中列出的特定资源类型。我们强烈建议您将条件的适用范围限制为目标资源类型。如果角色包含对未提供 resource.name
特性的资源类型的权限,您应确保这些权限不受检查 resource.name
的条件的一部分限制。
以下示例演示如何确保此行为。在此示例中,条件允许访问除 Cloud Storage 存储分区和对象以外的所有资源类型。相比之下,对于存储分区和对象,条件仅允许访问存储分区 example-bucket
及其包含的对象:
(resource.type != 'storage.googleapis.com/Bucket' &&
resource.type != 'storage.googleapis.com/Object') ||
resource.name.startsWith('projects/_/buckets/example-bucket')
请注意,条件的第一部分会检查资源是否不是存储分区和对象。如果资源的类型不同,则无论资源名称如何,整个条件求得的值为 true
。
另请注意,条件会检查 resource.type
特性而非 resource.service
特性。检查 resource.type
特性有以下几个好处:
- 它会将
resource.name
检查限制为适当的资源集。例如,如果您要授予具有特定名称的 Compute Engine 实例的访问权限,则可以排除 Compute Engine 实例以外的所有资源类型。 - 如果服务将来添加了新的资源类型,它将阻止条件范围更改。
您可以使用 extract()
函数从资源名称中提取值。
例如,您可以从 Compute Engine 虚拟机实例的资源名称中提取项目 ID,然后编写引用该项目 ID 的条件表达式。如需了解详情,请参阅本页面上的从特性中提取值。
特性变量 | resource.name |
||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
特性类型 | 字符串 | ||||||||||||
支持的运算符 |
startsWith() 、endsWith() 、extract() 、== 、!=
|
||||||||||||
支持的操作数 |
字符串 每种资源类型都为资源名称使用一种特定格式。如需查看这些格式的列表,请参阅资源名称格式。 |
||||||||||||
讨论 |
|
||||||||||||
示例 |
示例 1(对于 Compute Engine 虚拟机实例):
示例 2(对于 Cloud Storage 存储分区):
示例 3(对于 Cloud Storage 对象):
示例 4(对于多种资源类型):
示例 5(对于 Cloud Storage 存储分区):
|
||||||||||||
支持的资源类型 |
|
资源标记
借助资源标记的函数,您可以根据资源关联到或继承自的标记设置条件。例如,您可以设置条件,以仅对关联了标记 env: prod
的资源授予角色。如需详细了解如何使用标记控制访问权限,请参阅标记和访问权限控制。
每个标记由一个键和一个值组成。每个键和值都有几种不同类型的标识符:
-
永久 ID,它是全局唯一的,并且永远不能重复使用。例如,标记键可以具有永久 ID
tagKeys/123456789012
,而标记值可以是永久 IDtagValues/567890123456
。 -
短名称。每个键的短名称必须在您的组织内具有唯一性,并且每个值的简短名称对于关联的键而言必须是唯一的。例如,标记键可以具有短名称
env
,标记值可以简称为prod
。 -
命名空间名称:将组织的数字 ID 添加到标记键的简称。例如,标记键可以具有命名空间名称
123456789012/env
。了解如何获取组织 ID。
如需了解如何选择要在条件中使用的标识符类型,请参阅标记定义和标识符。
您可以使用以下函数处理标记:
函数 | 类型 | 说明 |
---|---|---|
resource.hasTagKey |
String --> bool |
函数:
检查请求的资源是否包含具有指定键的标记。标记键通过其命名空间名称查找。如需使用标记键的永久 ID 检查是否存在标记键,请使用函数
参数:String:标记键的命名空间名称,并将组织的数字 ID 和正斜杠作为前缀。例如 示例:
|
resource.hasTagKeyId |
String --> bool |
函数:
检查请求的资源是否包含具有指定键的标记。标记键通过其永久 ID 查找。如需使用标记键的命名空间名称检查是否存在标记键,请使用函数
参数:字符串:标记键的永久 ID。
例如 示例:
|
resource.matchTag |
(String, String) --> 布尔值 |
函数:
检查请求的资源是否包含带有指定键和值的标记。键通过其命名空间名称查询,值通过其短名称查询。如需使用永久 ID 检查标记键和值,请使用函数 参数:
第一个 String 参数是标记键的命名空间名称,带有组织的数字 ID 和正斜杠作为前缀。例如:
第二个 String 参数是标记值的短名称。例如: 示例:
|
resource.matchTagId |
(String, String) --> 布尔值 |
函数:
检查请求的资源是否包含带有指定键和值的标记。键和值通过其永久 ID 查找。如需使用标记键的命名空间名称和使用其短名称的值检查标记键,请使用函数 参数:
第一个 String 参数是标记键的永久 ID。例如:
第二个 String 参数是标记值的永久性 ID。例如: 示例:
|
请求特性
通过“请求特性”,您可以创建条件来评估请求的详细信息,例如其访问权限级别、日期/时间、目标 IP 地址和端口(适用于 IAP TCP 隧道)或预期网址主机/路径(适用于 IAP)。
访问权限级别特性
借助访问权限级别特性,用户可以设置条件,规定只有在请求满足特定访问权限级别时才能为其授权。
访问权限级别特性派生自请求的特性(例如源 IP 地址、设备特性、一天中的时间等)。例如,名为 fullyTrusted
的访问权限级别可能会要求发出请求的设备归公司所有,并设置了屏幕锁定。onNetwork
访问权限级别可能要求发出请求的设备源自特定的 IP 地址范围。如需详细了解访问权限级别,请参阅 Access Context Manager 文档。
访问权限级别特性仅适用于以下情况:您使用 Identity-Aware Proxy 访问隧道实例,或者访问在 App Engine 或 Compute Engine 后端服务上运行的 Web 应用。具体而言,访问权限级别特性仅适用于检查以下其中一项权限的请求:
iap.tunnelInstances.accessViaIAP
iap.webServiceVersions.accessViaIAP
有条件地授予以下预定义角色时,您可以使用访问权限级别特性:
IAP-secured Tunnel User (
roles/iap.tunnelResourceAccessor
)包含一项权限:
iap.tunnelInstances.accessViaIAP
。IAP-secured Web App User (
roles/iap.httpsResourceAccessor
)包含一项权限:
iap.webServiceVersions.accessViaIAP
。
您还可以使用访问权限级别特性来有条件地授予包含这些权限的自定义角色。自定义角色不得包含任何其他权限。
request.auth.access_levels
特性
特性变量 | request.auth.access_levels |
---|---|
特性类型 | 字符串列表 |
支持的运算符 | in |
支持的操作数 | 字符串 |
讨论 |
变量 访问权限级别的全名采用以下名称格式: 注意:访问权限级别字符串区分大小写,且必须与 Access Context Manager 中的配置完全匹配才能产生预期作用。例如,“accessPolicies/199923665455/accessLevels/CorpNet”是要在表达式中使用的有效字符串文本,而“accessPolicies/199923665455/accesslevels/CorpNet”无法产生预期作用。 |
示例 |
"accessPolicies/199923665455/accessLevels/CorpNet" |
支持的资源类型 | 适用于使用 Identity-Aware Proxy 访问隧道实例或在 App Engine 上运行的 Web 应用的请求 |
API 特性
API 特性可帮助您根据特定 Google Cloud API 或服务提供的数据管理访问权限。
例如,当您使用 Cloud Storage 列出存储分区中的对象时,可以在请求中使用 prefix
参数,以便仅包含名称以特定前缀开头的对象。如果您使用凭据访问边界来缩小短期有效的凭据范围,则可以创建凭据访问边界,用于通过检查 API 特性 storage.googleapis.com/objectListPrefix
来限制列出对象的权限。此 API 特性包含请求中 prefix
参数的值。
如需查看何时可能需要在条件中使用 API 特性的示例,请参阅以下页面:
请参阅以下部分,了解哪些服务可识别 API 特性。
适用于 API 特性的函数
您可以使用以下函数来处理 API 特性:
函数 | 类型 | 说明 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
api.getAttribute |
(String, T) --> T |
函数:获取请求的 API 特性。 参数: String:要获取的 API 特性。如需了解支持的值,请参阅本页面上的 Cloud Storage API 特性和 IAM API 特性。
T:当没有 API 特性时要使用的默认值。请使用与 API 特性值相同的类型。例如,如果 API 特性的值是字符串,则您可以使用空字符串或占位符字符串,例如 示例:
|
||||||||||||
hasOnly |
List<T>.(List<T>) --> bool |
函数:检查列表是仅包含允许的项,还是其中部分项。 参数:
List<T>:类型为 T 的项列表。您对 示例:
检查请求将授予还是撤消除 Pub/Sub Editor (
|
Cloud Storage API 特性
Cloud Storage 提供以下 API 特性。
特性 | 类型 | 说明 |
---|---|---|
storage.googleapis.com/objectListPrefix |
字符串 |
对于列出存储分区中的对象的请求,包含请求中 对于其他类型的请求,该特性未定义。 可识别此特性的服务: 只有 Cloud Storage 能够识别此特性。 |
IAM API 特性
IAM 提供以下 API 特性:
属性 | 类型 | 说明 |
---|---|---|
iam.googleapis.com/modifiedGrantsByRole |
数组 |
对于设置资源的 IAM 政策的请求,此特性包含请求修改的角色绑定中的角色名称。 对于其他类型的请求,该特性未定义。 接受此特性的资源:
以下资源接受其 IAM 政策中具有
可识别此特性的服务:
以下服务可识别
|
日期/时间特性
日期/时间特性用于设置对 Google Cloud 资源的可过期、计划的或限时的访问权限。
此特性适用于所有 Google Cloud 服务和资源类型。
支持的基本函数和运算符
用于日期/时间特性的特性变量为 request.time
,其类型为时间戳。您还可以将字符串转换为时间戳和时长类型。
支持的基本函数 | 类型 | 说明 |
---|---|---|
date |
String --> Timestamp |
函数:将字符串转换为时间戳。 示例:
|
duration |
String --> Duration |
函数:将字符串转换为时长。 示例:
|
|
String --> Timestamp |
函数:将字符串转换为时间戳。 示例:
重要提示: |
|
(Timestamp, Timestamp) --> bool |
函数:与时间戳类型的常规比较。 示例: |
+ 、- |
(Timestamp, Duration) --> Timestamp |
函数:在时间戳的基础上加上或减去时长。 示例:
|
支持的高级函数和运算符
用于日期/时间特性的特性变量为 request.time
,类型为时间戳。
支持的高级函数 | 类型 | 说明 |
---|---|---|
|
(int, int) --> bool |
函数:对 int 类型的值执行常规比较。 讨论: |
|
Timestamp.() --> int |
函数: 参数: 示例: 示例: 示例: |
|
Timestamp.() --> int |
函数:获取日期的年份。 参数: 示例: 示例: |
|
Timestamp.() --> int |
函数:获取日期的小时数;值介于 0 到 23 之间。 参数: 示例: 注意: |
|
Timestamp.() --> int |
函数:根据时间戳获取一秒中的毫秒数;值介于 0 到 999 之间。 参数: 注意: |
|
Timestamp.() --> int |
函数:根据时间戳获取一小时中的分钟数;值介于 0 到 59 之间。 参数: 注意: |
|
Timestamp.() --> int |
函数:根据时间戳获取一年中的月数;值介于 0 到 11 之间。 参数: 示例: |
|
Timestamp.() --> int |
函数:根据时间戳获取一分钟中的秒数;值介于 0 到 59 之间。 参数: 注意: |
目标 IP/端口特性
目标 IP 地址/端口特性允许用户根据请求的内部目标 IP 地址和/或端口来管理访问权限。
例如,Compute Engine 虚拟机实例可能会将外部 IP 地址和端口 132.168.42.21:3001
映射到内部 IP 地址和端口 10.0.0.1:2300
以供一般使用。相比之下,内部 IP 地址和端口 10.0.0.1:22
可能仅在内部供管理使用。您可以使用目的地 IP/端口特性,根据内部 IP 地址和端口授予不同数量的访问权限。
如需详细了解 TCP 转发,请参阅 Identity-Aware Proxy 文档。
destination.ip
特性
特性变量 | destination.ip |
---|---|
特性类型 | 字符串 |
支持的运算符 | ==, != |
支持的操作数 | 字符串 |
讨论 |
变量 注意: |
示例 |
destination.ip == "10.0.0.1" destination.ip != "10.0.0.1" |
支持的资源类型 | 适用于使用 Identity-Aware Proxy 访问隧道实例的请求 |
destination.port
特性
特性变量 | destination.port |
---|---|
特性类型 | 整数 |
支持的运算符 | ==, !=, <, <=, >, >= |
支持的操作数 | 整数 |
讨论 |
变量 |
示例 |
destination.port == 21 destination.port < 3001 |
支持的资源类型 | 适用于使用 Identity-Aware Proxy 访问隧道实例的请求 |
转发规则特性
借助转发规则特性,您可以指定成员可以创建的转发规则的类型。例如,您可以允许成员为内部 Google Cloud 负载平衡器(用于处理源自 Google Cloud 网络的流量)创建转发规则,但不允许为外部 Google Cloud 负载平衡器(用于处理源自互联网的流量)创建转发规则。
对于 Cloud Load Balancing,转发规则特性不会影响创建 Google Cloud 负载平衡器的其他组件(例如后端服务、目标代理、运行状况检查和网址映射)的能力。
支持的函数
支持的函数 | 类型 | 说明 |
---|---|---|
compute.isForwardingRule |
() --> bool |
函数:检查请求是否正在创建转发规则。 示例:查看 |
compute.matchLoad |
Array.(string)--> bool |
函数:检查请求是否会影响指定类型的负载平衡方案。如需查找每种负载平衡方案的标识符以及详细了解每种方案,请参阅在 Google Cloud 负载平衡器上使用 IAM Conditions。 参数:字符串数组 示例:
|
支持的资源类型
该特性适用于创建以下某种资源类型的请求:
服务 | 资源类型 |
---|---|
Cloud Load Balancing | 转发规则 |
Cloud VPN | 转发规则(全球和区域) |
Compute Engine | 转发规则(用于协议转发) |
Traffic Director1 | 转发规则 |
1 使用 Compute Engine 的资源特性。
网址路径/主机特性
通过网址路径/主机特性,用户可以根据请求的网址路径和/或主机来管理访问权限。例如,某项条件可以指定 https://example.com
是可供用户的常规网域访问的主应用,而 https://hr.example.com/admin
用于访问应用中只有人力资源管理员才能访问的部分下的某个页面。
request.path
特性
特性变量 | request.path |
---|---|
特性类型 | 字符串 |
支持的运算符 | ==, 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") 此函数中使用表示网址路径后缀的字符串。 |
支持的资源类型 |
Identity-Aware Proxy 应用服务版本 (App Engine) 适用于使用 Identity-Aware Proxy 访问 App Engine 或 Compute Engine 上运行的 Web 应用的请求 |
request.host
特性
特性变量 | request.host |
---|---|
特性类型 | 字符串 |
支持的运算符 | ==, 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") 表示网站主机名后缀的字符串。 |
支持的资源类型 |
Identity-Aware Proxy 应用服务版本 (App Engine) 适用于使用 Identity-Aware Proxy 访问应用服务版本的请求。 |
从特性中提取值
您可以使用 extract()
函数从特性中提取值。例如,您可以提取资源名称的任意部分,然后编写引用您所提取的文本的条件表达式。
如需使用 extract()
函数,请提供一个提取模板,用于指定要提取的特性部分。例如,如果您要从 Compute Engine 虚拟机实例的资源名称中提取项目 ID,可以使用模板 projects/{project-id}/
。
提取模板包含以下组成部分:
括号内的标识符,用于标识要提取的子字符串。请选择一个有意义的简短标识符,明确指出要提取的值。您可以使用从
A
到Z
的大写和小写字母、数字、短划线 (-
)、和下划线 (_
)。在模板
projects/{project-id}/
中,标识符为project-id
。可选:前缀,它必须出现在要提取的子字符串之前。
在模板
projects/{project-id}/
中,前缀为projects/
。可选:后缀,它必须出现在要提取的子字符串之后。
在模板
projects/{project-id}/
中,后缀为/
。
根据提取模板是否带有前缀、后缀或者两者兼有,extract()
函数会返回不同的值:
有前缀 | 有后缀 | 提取的值 |
---|---|---|
— | — | 资源的完整名称 |
— | 第一处出现的前缀后的字符,如果前缀后面没有字符,则为空字符串 | |
— | 第一处出现的后缀前的字符,如果后缀前面没有字符,则为空字符串 | |
第一处出现的前缀与其后第一处出现的后缀之间的字符,如果该前缀与该后缀之间没有字符,则为空字符串 |
如果您指定的前缀或后缀未出现在特性中,或后缀仅出现在前缀之前,则 extract()
函数会返回 null
。
以下示例展示了几个不同提取模板的输出结果。这些示例引用了 Cloud Storage 对象的资源名称 projects/_/buckets/acme-orders-aaa/data_lake/orders/order_date=2019-11-03/aef87g87ae0876
:
提取模板 | 输出 |
---|---|
/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/{none}/order_date= |
null |
/orders/order_date=2019-11-03/ |
null |
如果您提取表示日期的字符串,则可以使用本页面上的日期/时间函数和运算符将提取的值转换为时间戳。如需查看示例,请参阅配置基于资源的访问权限。