此页面由 Cloud Translation API 翻译。

自定义访问权限级别规范

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

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

对象

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

物体
`origin`	包含用于标识请求来源的属性。
`request.auth`	包含用于标识请求的身份验证和授权方面的属性。
`levels`	包含用于定义依赖于其他访问权限级别的属性。
`device`	包含描述请求来源设备的属性。

`origin` 属性

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

属性

ip

类型字符串

说明

发出请求的 IP 地址。如果无法确定 IP 地址，origin.ip 会评估为错误。我们建议您使用 inIpRange，用于检查源 IP 地址是否位于而不是进行字符串比较。

警告：请勿将 origin.ip 与空字符串进行比较。行为未定义。

例如：

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

region_code

类型字符串

说明

ISO 3166-1 alpha-2 代码。发起请求如果无法确定区域代码，origin.region_code 的评估结果为错误。

警告：请勿比较 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

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

`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 属性的可用密钥因供应商而异。在政策表达式中比较键值对时，请确保一致性。例如，如果您希望键值对为字符串或布尔值，请确保相应地在政策表达式中将其与字符串或布尔值进行比较。请注意，当值是整数时，应在政策表达式中将其与双精度数字进行比较。

枚举值：

// 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

注意：is_device_compromised 只是一个示例，表示由供应商定义的密钥。

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 扩展程序函数确定请求时提供的证书与设备注册端点验证时注册的其中一个设备证书相匹配。

自定义访问权限级别规范

对象

origin 属性

request.auth 属性

levels 特性

device 特性

函数

CEL 表达式的宏

CEL 表达式示例

示例 1

示例 2

示例 3

`origin` 属性

`request.auth` 属性

`levels` 特性

`device` 特性