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 .
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. |
request.time
|
Contains time-based attributes that you can use to restrict access to resources based on the time of day, day of the week, or a specific date range. |
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.
ip
| Type | string |
| Description | The IP address the request originated from. If the IP address
cannot be determined, Example: inIpRange ( 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. If the region code cannot be
determined, 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.
principal
| Type | string, list(string) |
| Description | The unique ID of the user who issued the request. The value for The value must be in the following format: Where UUID is the UUID of a user. Example: 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
| Type | boolean |
| Description | User authenticated with a password. Example: request.auth.claims.crd_str.pwd == true |
claims.crd_str.push
| Type | boolean |
| Description | User authenticated with a push notification to the mobile device. Example: request.auth.claims.crd_str.push == true |
claims.crd_str.sms
| Type | boolean |
| Description | User authenticated using a code sent to SMS or via a phone call. Example: request.auth.claims.crd_str.sms == true |
claims.crd_str.swk
| Type | boolean |
| Description | 2SV used a software key, such as a phone, as security key. Example: request.auth.claims.crd_str.swk == true |
claims.crd_str.hwk
| Type | boolean |
| Description | 2SV used a hardware key, such as Google Titan Key. Example: request.auth.claims.crd_str.hwk == true |
claims.crd_str.otp
| Type | boolean |
| Description | User authenticated with one time password methods (Google Authenticator and Backup Codes). Example: request.auth.claims.crd_str.otp == true |
claims.crd_str.mfa
| Type | boolean |
| Description | User authenticated with any of the methods in this table except pwd. Example: request.auth.claims.crd_str.mfa == true |
For more information about credential strength policy, see Configuring a credential strength policy .
request.time
attributes
This section lists the attributes supported by the request.time
object.
getFullYear()
| Type | string |
| Description | Retrieves the year (example: 2023). Example: |
getMonth()
| Type | string |
| Description | Retrieves the month, from 0 (January) to 11 (December). Example: |
getDate()
| Type | string |
| Description | Retrieves the day of the month, from 1 to 31. Example: |
getDayOfMonth()
| Type | string |
| Description | Retrieves the day of the month, from 0 to 30 (0 is the 1st day). Example: |
getDayOfWeek()
| Type | string |
| Description | Retrieves the day of the week, from 0 (Sunday) to 6 (Saturday). Example: |
getDayOfYear()
| Type | string |
| Description | Retrieves the day of the year, from 0 to 365. Example: |
getHours()
| Type | string |
| Description | Retrieves the hour of the day, from 0 (midnight) to 23 (11 PM). Example: |
getMinutes()
| Type | string |
| Description | Retrieves the minute of the hour, from 0 to 59. Example: |
levels
attribute
This section lists the attributes supported by the levels
object.
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 |
device
attribute
This section lists the attributes supported by the device
object. If no device
associated to the identifiers in the request is found, all of the following
attributes will evaluate to an error.
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 Additionally, vendors may provide their own keys and values
that are referenced using the To reference device state
, use the format Enum values: // 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 ; } 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 device.vendors [ "some_vendor" ] . data [ "some_num" ] == 1.0 |
android_device_security.verified_boot
| Type | boolean |
| Description | Whether the Android verified boot
status is Example: device.android_device_security.verified_boot == true |
android_device_security.cts_profile_match
| Type | boolean |
| Description | Whether device passes CTS profile compliance . Example: device.android_device_security.cts_profile_match == true |
android_device_security.verify_apps_enabled
| Type | boolean |
| Description | Whether the device has Google Play Protect Verify Apps enabled. Example: device.android_device_security.verify_apps_enabled == true |
android_device_security.has_potentially_harmful_apps
| Type | boolean |
| Description | Whether potentially harmful apps were found on the device. Example: device.android_device_security.has_potentially_harmful_apps == true |
ios_device_security.is_device_jailbroken
| Type | boolean |
| Description | Whether the iOS device was found to be jailbroken . Example: device.ios_device_security.is_device_jailbroken == 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 |
chrome.management_state
Is the browser managed, at the browser level or at the profile level, and by the enterprise under the correct domain.
A browser is considered to be managed if the policies are centrally managed and pushed, and that the domain of the managed browser or profile matches the expected domain on the server side.
Following are the available Chrome management states:
| State | |
|---|---|
MANAGED
|
The browser or profile is managed by the customer. |
UNMANAGED
|
The browser or profile is not managed by any customer. |
MANAGED_BY_OTHER_DOMAIN
|
The browser or profile is managed by some other customer. |
PROFILE_MANAGED
|
The profile is managed by the customer. |
BROWSER_MANAGED
|
The browser is managed by the customer. |
Example:
device.chrome.management_state in [ ChromeManagementState.CHROME_MANAGEMENT_STATE_BROWSER_MANAGED , ChromeManagementState.CHROME_MANAGEMENT_STATE_PROFILE_MANAGED , ]
chrome.versionAtLeast
| Type | string |
| Description | Is the browser above a certain minimum version. Example: device.chrome.versionAtLeast ( "88.0.4321.44" ) |
chrome.is_realtime_url_check_enabled
| Type | boolean |
| Description | Is the real-time URL check connector enabled. Example: device.chrome.is_realtime_url_check_enabled == true | false |
chrome.is_file_upload_analysis_enabled
| Type | boolean |
| Description | Is the file upload analysis connector enabled. Example: device.chrome.is_file_upload_analysis_enabled == true | false |
chrome.is_file_download_analysis_enabled
| Type | boolean |
| Description | Is the file download analysis connector enabled. Example: device.chrome.is_file_download_analysis_enabled == true | false |
chrome.is_bulk_data_entry_analysis_enabled
| Type | boolean |
| Description | Is the bulk text (paste) analysis connector enabled. Example: device.chrome.is_bulk_data_entry_analysis_enabled == true | false |
chrome.is_security_event_analysis_enabled
| Type | boolean |
| Description | Is the security event reporting connector enabled. Example: device.chrome.is_security_event_analysis_enabled == true | false |
device.certificates.exists
| Type | boolean |
| Description | A list of enterprise certificates associated with the device. This attribute is used with macros to iterate through the certificates and check their properties, such as validity. Example: // Checks if the device has at least one valid enterprise certificate. device.certificates.exists ( cert , cert.is_valid == true ) |
Functions
Access Context Manager provides the following functions for use in the CEL expressions for custom access levels.
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" ]) |
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 Example: device.versionAtLeast ( "10.0" ) == true |
certificateBindingState(origin, device)
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_MATCHING_EXISTING_DEVICE -
CertificateBindingState.CERT_STATE_UNKNOWN
Example:
certificateBindingState ( origin , device ) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE
startsWith()
| Type | string.(string) -> bool |
| Description | Tests whether the string operand starts with the prefix argument. Example: "Sample string" . startsWith ( "Sample" ) |
endsWith()
| Type | string.(string) -> bool |
| Description | Tests whether the string operand ends with the suffix argument. Example: "Sample string" . endsWith ( "string" ) |
origin.clientCertFingerprint()
| Type | Origin.() -> string |
| Description | Returns the fingerprint of the certificate associated with the origin. You can use this in macros to test device certificates. Example: // Checks if the enterprise certificate associated with the origin matches the device. device.certificates.exists ( cert , cert.is_valid && cert.cert_fingerprint == origin.clientCertFingerprint ()) |
Macros for CEL expressions
You can use the following macros in the CEL expressions for custom access levels:
| Macro | Description |
|---|---|
has(e.f)
|
Tests whether a field is available. See Field Selection
for more details. Example: |
e.all(x, p)
|
Tests whether a predicate holds for all elements of a list e
or keys of a map e
. Here x
is an identifier to be used in p
which binds to the element or key. The all()
macro combines per-element predicate results with the and
(&&) operator, so if any predicate evaluates to false, the macro evaluates to false, ignoring any errors from other predicates. Example: This returns false because not all elements are greater than 1: |
e.exists(x, p)
|
Like the all()
macro, but combines the predicate results with the or
(||) operator. Example: This returns true because there is at least one element in the list greater than 1: Checks if the enterprise certificate associated with the device matches the issuer: |
e.exists_one(x, p)
|
Like the exists()
macro, but evaluates to true only if the predicate of exactly one element or key evaluates to true, and the rest to false. Any other combination of boolean results evaluates to false, and any predicate error causes the macro to raise an error. Example: This returns false because more than one element is greater than 1: |
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
certificateBindingStateextension 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 .
