自定义访问权限级别规范

本页详细介绍了用于为自定义访问权限级别构建通用表达式语言 (CEL) 表达式的对象和属性。其中包含示例。

如需详细了解 CEL，请参阅 CEL 语言定义。

对象

Access Context Manager 提供四个包含访问权限级别属性的对象。

物体
origin 包含用于标识请求来源的属性。
request.auth 包含用于标识请求的身份验证和授权方面的属性。
request.time 包含基于时间的属性，您可以使用这些属性根据一天中的时间、一周中的日期或特定日期范围来限制对资源的访问权限。
levels 包含用于定义依赖于其他访问权限级别的属性。
device 包含描述请求来源设备的属性。

origin 属性

本部分列出了 origin 对象支持的属性。

属性
ip
类型 字符串
说明

发出请求的 IP 地址。如果无法确定 IP 地址，origin.ip 的计算结果为错误。建议您使用 inIpRange 检查来源 IP 地址是否在特定 IP 地址范围内，而不是进行字符串比较。

例如： 

inIpRange(origin.ip, ["203.0.113.24"])

region_code
类型 字符串
说明

发出请求的国家或区域的 ISO 3166-1 alpha-2 代码。如果无法确定区域代码，则 origin.region_code 会评估为错误。

例如： 

origin.region_code == "GB"
origin.region_code in ["US", "FR", "JP"]

request.auth 属性

本部分列出了 request.auth 对象支持的属性。

属性
principal
类型 字符串、列表（字符串）
说明

发出请求的用户的唯一 ID。

request.auth.principal 的值必须是一个或多个唯一身份用户 ID。您可以使用 Admin SDK Directory API 获取这些 UUID。

该值必须采用以下格式：https://accounts.google.com/UUID

其中，UUID 是用户的 UUID。

例如： 

request.auth.principal == "https://accounts.google.com/1134924314572461055"
request.auth.principal in ["https://accounts.google.com/1134924314572461055", "https://accounts.google.com/3134824314572461115"]

claims.crd_str.pwd
类型 布尔值
说明

使用密码对用户进行身份验证。

例如： 

request.auth.claims.crd_str.pwd == true

claims.crd_str.push
类型 布尔值
说明

通过向移动设备推送通知对用户进行身份验证。

例如： 

request.auth.claims.crd_str.push == true

claims.crd_str.sms
类型 布尔值
说明

使用通过短信发送的代码或者通过电话告知的代码对用户进行身份验证。

例如： 

request.auth.claims.crd_str.sms == true

claims.crd_str.swk
类型 布尔值
说明

两步验证使用软件键（例如手机）作为安全键。

例如： 

request.auth.claims.crd_str.swk == true

claims.crd_str.hwk
类型 布尔值
说明

两步验证使用硬件键，例如 Google Titan 键。

例如： 

request.auth.claims.crd_str.hwk == true

claims.crd_str.otp
类型 布尔值
说明

使用动态密码方法（Google 身份验证器和备用验证码）对用户进行身份验证。

例如： 

request.auth.claims.crd_str.otp == true

claims.crd_str.mfa
类型 布尔值
说明

使用此表中的任何方法（pwd 除外）对用户进行身份验证。

例如： 

request.auth.claims.crd_str.mfa == true

如需详细了解凭据强度政策，请参阅配置凭据强度政策。

request.time 属性

本部分列出了 request.time 对象支持的属性。

属性
getFullYear()
类型 字符串
说明

检索年份（例如：2023 年）。

例如：

request.time.getFullYear("America/Los_Angeles") == 2024

getMonth()
类型 字符串
说明

检索月份，范围为 0（1 月）到 11（12 月）。

例如：

request.time.getMonth("America/Los_Angeles") == 0（1 月）

getDate()
类型 字符串
说明

检索一个月中的某天（从 1 到 31）。

例如：

request.time.getDate("America/Los_Angeles") == 1

getDayOfMonth()
类型 字符串
说明

检索月份中的日期，范围为 0 到 30（0 为第 1 天）。

例如：

request.time.getDayOfMonth("America/Los_Angeles") == 0（每月 1 日）

getDayOfWeek()
类型 字符串
说明

检索周几，从 0（星期日）到 6（星期六）。

例如：

request.time.getDayOfWeek("America/Los_Angeles") == 1（周一）

getDayOfYear()
类型 字符串
说明

检索一年中的某天，范围为 0 到 365。

例如：

request.time.getDayOfYear("America/Los_Angeles") == 0（1 月 1 日）

getHours()
类型 字符串
说明

检索一天中的小时，范围从 0（午夜）到 23（晚上 11 点）。

例如：

request.time.getHours("America/Los_Angeles") == 19（晚上 7 点）

getMinutes()
类型 字符串
说明

检索小时中的分钟数，范围为 0 到 59。

例如：

request.time.getMinutes("America/Los_Angeles") == 30

levels 属性

本部分列出了 levels 对象支持的属性。

属性
level name
类型 布尔值
说明

level name 对应现有访问权限级别的名称。

使用时，除了自定义访问权限级别的其他要求外，还必须满足指定访问权限级别的条件。

示例： 

levels.allow_corp_ips

其中，allow_corp_ips 是访问权限级别的名称。

device 特性

本部分列出了 device 对象支持的属性。如果未找到与请求中的标识符相关联的任何设备，则以下所有属性都将评估为错误。

特性
encryption_status
类型 枚举
说明

描述设备的加密状态。

枚举值：

enum DeviceEncryptionStatus {
  // The encryption status of the device is not specified or not known.
  ENCRYPTION_UNSPECIFIED == 0;
  // The device does not support encryption.
  ENCRYPTION_UNSUPPORTED == 1;
  // The device supports encryption, but is currently unencrypted.
  UNENCRYPTED == 2;
  // The device is encrypted.
  ENCRYPTED == 3;
}

示例： 

device.encryption_status == DeviceEncryptionStatus.ENCRYPTED

is_admin_approved_device
类型 布尔值
说明

设备是否已获得网域管理员的批准。

示例： 

device.is_admin_approved_device == true

is_corp_owned_device
类型 布尔值
说明

设备是否归组织所有。

示例： 

device.is_corp_owned_device == true

is_secured_with_screenlock
类型 布尔值
说明

设备是否启用了屏幕锁定功能。

示例： 

device.is_secured_with_screenlock == true

os_type
类型 枚举
说明

标识设备正在使用的操作系统。

枚举值：

enum OsType {
  // The operating system of the device is not specified or not known.
  OS_UNSPECIFIED == 0;
  // A desktop Mac operating system.
  DESKTOP_MAC == 1;
  // A desktop Windows operating system.
  DESKTOP_WINDOWS == 2;
  // A desktop Linux operating system.
  DESKTOP_LINUX == 3;
  // An Android operating system.
  ANDROID == 4;
  // An iOS operating system.
  IOS == 5;
  // A desktop ChromeOS operating system.
  DESKTOP_CHROME_OS == 6;
}

示例： 

device.os_type == OsType.DESKTOP_MAC
device.os_type != OsType.OS_UNSPECIFIED

vendors
类型 映射<string, Vendor>供应商；
说明

vendors 对象用于访问第三方安全和端点管理供应商提供的数据。每个供应商都可以填充三个共享的顶级属性：is_compliant_device、is_managed_device 和 device_health_score。

此外，供应商可以提供使用 data 属性引用的自己的密钥和值。data 属性的可用密钥因供应商而异。 在政策表达式中比较键值对时，请确保一致性。例如，如果您希望键值对为字符串或布尔值，请确保相应地在政策表达式中将其与字符串或布尔值进行比较。请注意，当值是整数时，应在政策表达式中将其与双精度数字进行比较。

如需引用设备状态，请使用 key-acme 格式，其中 acme 是组织的客户 ID。您可以从 GET https://www.googleapis.com/admin/directory/v1/customers/my_customer 网址中获取客户 ID。响应中的 ID 字段包含以字母 C 开头的客户 ID。使用字母 C 后面的字符串（不包括字母 C）作为客户 ID。

枚举值：

// Health score of the device as provided by the vendor (possibly third party).
enum DeviceHealthScore {
  // The health score for the device is not specified or unknown.
  DEVICE_HEALTH_SCORE_UNSPECIFIED = 0;
  // The health of the device is very poor.
  VERY_POOR = 1;
  // The health of the device is poor.
  POOR = 2;
  // The health of the device is ok.
  NEUTRAL = 3;
  // The health of the device is good.
  GOOD = 4;
  // The health of the device is very good.
  VERY_GOOD = 5;
}

示例： 

device.vendors["some_vendor"].is_compliant_device == true
 

device.vendors["some_vendor"].is_managed_device == true
 

device.vendors["some_vendor"].device_health_score == DeviceHealthScore.VERY_GOOD
 

device.vendors["some_vendor"].data["is_device_compromised"] == true
 

device.vendors["some_vendor"].data["some_num"] == 1.0

android_device_security.verified_boot
类型 布尔值
说明

Android 启动时验证状态是否为 green。

例如： 

device.android_device_security.verified_boot == true

android_device_security.cts_profile_match
类型 布尔值
说明

设备是否通过 CTS 配置文件合规性检查。

例如： 

device.android_device_security.cts_profile_match == true

android_device_security.verify_apps_enabled
类型 布尔值
说明

设备是否已启用 Google Play 保护机制验证应用。

例如： 

device.android_device_security.verify_apps_enabled == true

android_device_security.has_potentially_harmful_apps
类型 布尔值
说明

设备上是否发现了潜在有害应用。

例如： 

device.android_device_security.has_potentially_harmful_apps == true
ios_device_security.is_device_jailbroken
类型 布尔值
说明

相应 iOS 设备是否被发现已越狱。

例如： 

device.ios_device_security.is_device_jailbroken == true

verified_chrome_os
类型 布尔值
说明

请求是否来自装有经过验证的 Chrome 操作系统的设备。

例如： 

device.verified_chrome_os == true

chrome.management_state
类型 字符串
说明

是否在浏览器级别或配置文件级别管理浏览器以及浏览器是否由正确网域中的企业管理。

如果政策是集中管理并推送的，并且受管理的浏览器或配置文件的网域与服务器端的预期网域匹配，则浏览器会被视为受管理的浏览器。

以下是可用的 Chrome 管理状态：

州
MANAGED 浏览器或个人资料由客户管理。
UNMANAGED 相应浏览器或个人资料未由任何客户管理。
MANAGED_BY_OTHER_DOMAIN 相应浏览器或个人资料由其他客户管理。
PROFILE_MANAGED 该商家资料由客户管理。
BROWSER_MANAGED 浏览器由客户管理。

例如： 

device.chrome.management_state in
    [
        ChromeManagementState.CHROME_MANAGEMENT_STATE_BROWSER_MANAGED,
        ChromeManagementState.CHROME_MANAGEMENT_STATE_PROFILE_MANAGED,
    ]

chrome.versionAtLeast
类型 字符串
说明

浏览器是否高于特定的最低版本。

例如： 

device.chrome.versionAtLeast("88.0.4321.44")

chrome.is_realtime_url_check_enabled
类型 布尔值
说明

是否启用实时网址检查连接器。

例如： 

device.chrome.is_realtime_url_check_enabled == true | false

chrome.is_file_upload_analysis_enabled
类型 布尔值
说明

是否启用文件上传分析连接器。

例如： 

device.chrome.is_file_upload_analysis_enabled == true | false

chrome.is_file_download_analysis_enabled
类型 布尔值
说明

是否启用文件下载分析连接器。

例如： 

device.chrome.is_file_download_analysis_enabled == true | false

chrome.is_bulk_data_entry_analysis_enabled
类型 布尔值
说明

是否启用批量文本（粘贴）分析连接器。

例如： 

device.chrome.is_bulk_data_entry_analysis_enabled == true | false

chrome.is_security_event_analysis_enabled
类型 布尔值
说明

是否启用安全性事件报告连接器。

例如： 

device.chrome.is_security_event_analysis_enabled == true | false

函数

Access Context Manager 提供以下函数，用于自定义访问权限级别的 CEL 表达式。

函数
inIpRange(address, [subnets])
类型 （字符串、列表（字符串）） -< 布尔值
说明

检查 IP 地址是否属于指定的子网。

例如： 

inIpRange(origin.ip, ["192.0.2.0/24", "198.51.100.0/24", "203.0.113.0/24"])

device.versionAtLeast(minVersion)
类型 DeviceType.（字符串）-> 布尔值
说明

检查设备操作系统是否至少为指定的版本。我们建议您将此函数与 device.os_type 属性搭配使用。

示例： 

device.versionAtLeast("10.0") == true

certificateBindingState(origin, device)
类型 （对等、DeviceType）-> 整数
说明

检查与来源关联的客户端证书是否与设备匹配，并报告状态。

函数返回的状态可以是以下任一状态：

  • CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE
  • CertificateBindingState.CERT_NOT_MATCHING_EXISTING_DEVICE
  • CertificateBindingState.CERT_STATE_UNKNOWN

例如： 

certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE

startsWith()
类型 string.(string) -> bool
说明

测试字符串操作数是否以前缀参数开头。

例如： 

"Sample string".startsWith("Sample")

endsWith()
类型 string.(string) -> bool
说明

测试字符串操作数是否以后缀参数结尾。

例如： 

"Sample string".endsWith("string")

origin.clientCertFingerprint()
类型 Origin.() -> string
说明

返回与来源关联的证书的指纹。您可以在宏中使用它来测试设备认证。

例如： 

// Checks if the enterprise certificate associated with the origin matches the device.
device.certificates.exists(cert, cert.is_valid && cert.cert_fingerprint == origin.clientCertFingerprint())

CEL 表达式的宏

您可以在 CEL 表达式中使用以下宏来自定义访问权限级别：

宏 说明
has(e.f) 测试某个字段是否可用。如需了解详情，请参阅字段选择。示例：

has({"key": "value"}.key) has(device.vendors.some_vendor)

e.all(x, p) 测试谓词是否支持列表 e 中的所有元素或映射 e 的键。此处 x 是要在绑定到元素或键的 p 中使用的标识符。all() 宏将每个元素的谓词结果与 and (&&) 运算符结合使用，因此如果任何谓词的计算结果为 false，则宏将评估为 false，并忽略其他谓词中的任何错误。例如：

此方法会返回 false，因为并非所有元素都大于 1：
[1,2,3].all(x, x > 1)

e.exists(x, p) 与 all() 宏类似，但将谓词结果与 or (||) 运算符组合使用。示例：

此示例返回 true，因为列表中至少有一个元素大于 1：
[1,2,3].exists(x, x > 1)

检查与设备关联的企业证书是否与颁发者匹配：
device.certificates.exists(cert, cert.is_valid && cert.issuer == "EMAILADDRESS=test_inter1@beyondcorp.in, CN=inter_1, OU=BCEDemo_1, O=BCEDemo, L=NCR, ST=UP, C=IN")

e.exists_one(x, p) 与 exists() 宏类似，但仅当恰好有一个元素或键的谓词计算结果为 true 且，其余为 false 时，计算结果为 true。布尔值结果的任何其他组合的计算结果为 false，任何谓词错误都会导致宏引发错误。示例：

如果有多个元素大于 1，则返回 false：
[1,2,3].exists_one(x, x > 1)

CEL 表达式示例

本部分将介绍用于创建自定义访问权限级别的 CEL 表达式示例。

示例 1

device.encryption_status == DeviceEncryptionStatus.ENCRYPTED && (origin.region_code in ["US"] || device.is_admin_approved_device)

此示例表示需要满足以下条件才能允许请求的访问权限级别：

  • 发出请求的设备已加密。

  • 以下一项或多项正确：

    • 请求来自美国。

    • 发出请求的设备已通过网域管理员的批准。

示例 2

(device.os_type == OsType.DESKTOP_WINDOWS && device.is_corp_owned_device) || (device.os_type == OsType.DESKTOP_MAC && device.is_admin_approved_device && device.versionAtLeast("10.11.0"))

此示例表示需要满足以下条件才能允许请求的访问权限级别：

  • 以下其中一项是正确的：

    • 发出请求的设备使用桌面 Windows 操作系统，并且归您的组织所有。

    • 发起请求的设备使用桌面 Mac 操作系统、经网域管理员批准并至少使用 MacOS 10.11。

示例 3

(certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE)

此示例表示需要满足以下条件才能允许请求的访问权限级别：

  • certificateBindingState 扩展程序函数确定请求时提供的证书与设备注册端点验证时注册的其中一个设备证书相匹配。