Console
    Contact Us Start free

    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 .

    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. If the IP address cannot be determined, origin.ip evaluates to an error. We recommend that you use inIpRange to check if the origin IP address is in a specific IP address range instead of doing a string comparison.

    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, origin.region_code evaluates to an error.

    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: https://accounts.google.com/ UUID

    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 .

    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. If no device associated to the identifiers in the request is found, all of the following attributes will evaluate to an error.

    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. Ensure that you are consistent when comparing the key value in your policy expression. For example, if you expect the key value to be a string or boolean, ensure that you compare it with a string or boolean in the policy expression correspondingly. Note that when the value is an integer, you should compare it with a double number in the policy expression.

    To reference device state , use the format key-acme where acme is the organization's customer ID. You can get the customer ID from the GET https://www.googleapis.com/admin/directory/v1/customers/my_customer URL. The ID field in the response contains the customer ID starting with the letter C . Use the string after the letter C , excluding the letter C , for the customer ID.

    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 green .

    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
    Type
    string
    Description

    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

    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" 
 ])
    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_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:

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

    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: [1,2,3].all(x, x > 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: [1,2,3].exists(x, x > 1)

    Checks if the enterprise certificate associated with the device matches the issuer: 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) 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: [1,2,3].exists_one(x, x > 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 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 .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: