Custom access level specification

This page details the objects and attributes that are used to the build the Common Expression Language (CEL) expressions for custom access levels. Examples are included.

To learn more about CEL, see the CEL language definition.

This page contains the following sections:

Objects

Access Context Manager provides four objects that contain access level attributes.

Objects
origin Contains attributes that identify the origin of the request.
request.auth Contains attributes that identify authentication and authorization aspects of the request.
levels Contains attributes to define dependency on other access levels.
device Contains attributes that describe the device the request originated from.

origin attributes

This section lists the attributes supported by the origin object.

Attributes
ip
Type string
Description

The IP address the request originated from.

Example: 

origin.ip == "203.0.113.24"

region_code
Type string
Description

The ISO 3166-1 alpha-2 code for the country or region where the request originated from.

Example: 

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

request.auth attributes

This section lists the attributes supported by the request.auth object.

Attributes
principal
Type string, list(string)
Description

The unique ID of the user who issued the request.

The value for request.auth.principal must be one or more unique user IDs. The UUIDs can be obtained using the Admin SDK Directory API.

The value must be in the following format: accounts.google.com/UUID

Where UUID is the UUID of a user.

Example: 

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

levels attribute

This section lists the attributes supported by the levels object.

Attributes
level name
Type boolean
Description

level name corresponds to the name of an existing access level.

When used, the conditions of the specified access level must also be met in addition to the other requirements of your custom access level.

Example: 

levels.allow_corp_ips

Where allow_corp_ips is the name of an access level.

device attribute

This section lists the attributes supported by the device object.

Attributes
encryption_status
Type enum
Description

Describes the encryption status of the device.

Enum values: 

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;
}

Example: 

device.encryption_status == DeviceEncryptionStatus.ENCRYPTED

is_admin_approved_device
Type boolean
Description

Whether the device has been approved by the domain administrator.

Example: 

device.is_admin_approved_device == true

is_corp_owned_device
Type boolean
Description

Whether the device is owned by the organization.

Example: 

device.is_corp_owned_device == true

is_secured_with_screenlock
Type boolean
Description

Whether the device has its screen lock function enabled.

Example: 

device.is_secured_with_screenlock == true

os_type
Type enum
Description

Identifies which operating system the device is using.

Enum values: 

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;
}

Example: 

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

vendors
Type map<string, Vendor> vendors;
Description

The vendors object is used to access data provided by third-party security and endpoint management vendors. Each vendor may populate three shared top-level attributes: is_compliant_device, is_managed_device, and device_health_score.

Additionally, vendors may provide their own keys and values that are referenced using the data attribute. The available keys for the data attribute vary from vendor to vendor.

Examples: 

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

verified_chrome_os
Type boolean
Description

Whether the request comes from a device with a verified Chrome OS.

Example: 

device.verified_chrome_os == true

Functions

Access Context Manager provides the following functions for use in the CEL expressions for custom access levels.

Functions
inIpRange(address, [subnets])
Type (string, list(string)) -< boolean
Description

Checks whether an IP address belongs to one of the given subnets.

Example: 

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

device.versionAtLeast(minVersion)
Type DeviceType.(string) -> boolean
Description

Checks whether the device operating system is at least a given version. We recommend that you use this function with the device.os_type attribute.

Example: 

device.versionAtLeast("10.0") == true

certificateBindingState(origin, device)
Type (Peer, DeviceType) -> integer
Description

Checks if the client certificate associated with the origin matches the device and reports the state.

The state returned by the function can be one of the following:

  • CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE
  • CertificateBindingState.CERT_NOT_MATCHES_EXISTING_DEVICE
  • CertificateBindingState.CERT_STATE_UNKNOWN

Example: 

certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE

Example CEL expressions

This section includes examples of CEL expressions used to create custom access levels.

Example 1

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

This example represents an access level that requires the following conditions be met in order to allow a request:

  • The device that the request originated from is encrypted.

  • One or more of the following is true:

    • The request originated in the United States.

    • The device that the request originated from is approved by the domain administrator.

Example 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"))

This example represents an access level that requires the following conditions be met in order to allow a request:

  • One of the following is true:

    • The device that the request originated from uses a desktop Windows operating system and is owned by your organization.

    • The device that the request originated from uses a desktop Mac operating system, is approved by the domain administrator, and is using at least MacOS 10.11.

Example 3

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

This example represents an access level that requires the following condition be met in order to allow a request:

  • The certificateBindingState extension function determines that the certificate presented at request time matches one of the device certificates that was registered when the device was enrolled in endpoint verification.