自定义访问权限级别规范

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

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

此网页包含以下部分：

对象
函数
CEL 表达式示例

对象

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

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

`origin` 属性

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

属性

ip

类型

字符串

说明

发出请求的 IP 地址。

示例：


origin.ip == "203.0.113.24"

region_code

类型

字符串

说明

发出请求的国家或地区的 ISO 3166-1 alpha-2 代码。

示例：


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。

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

其中，UUID 是用户的 UUID。

示例：


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

`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 属性的可用密钥因供应商而异。

示例：


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

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

verified_chrome_os

类型

布尔值

说明

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

示例：


device.verified_chrome_os == true

函数

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"]) == true

device.versionAtLeast(minVersion)

类型 DeviceType.（字符串）-> 布尔值

说明

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

示例：


device.versionAtLeast("10.0") == true

certificateBindingState(origin, device)

类型（对等、DeviceType）-> 整数

说明

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

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

CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE
CertificateBindingState.CERT_NOT_MATCHES_EXISTING_DEVICE
CertificateBindingState.CERT_STATE_UNKNOWN

示例：


certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE

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 表达式示例

示例 1

示例 2

示例 3

`origin` 属性

`request.auth` 属性

`levels` 属性

`device` 属性