自訂存取層級規格

本頁詳細說明用於建構自訂存取層級的一般運算語言 (CEL) 運算式的物件和屬性。並附上相關範例。

如要進一步瞭解 CEL,請參閱 CEL 語言定義

物件

Access Context Manager 提供四個包含存取層級屬性的物件。

物件
origin 包含可識別要求來源的屬性。
request.auth 包含可識別要求驗證和授權層面的屬性。
levels 包含定義其他存取層級依附元件的屬性。
device 包含用來描述要求來源裝置的屬性。

origin」屬性

本節列出 origin 物件支援的屬性。

屬性
ip
類型 字串
說明

產生要求的 IP 位址。如果無法判斷 IP 位址,origin.ip 會判定為錯誤。建議您使用 inIpRange 檢查來源 IP 位址是否位於特定 IP 位址範圍內,而非進行字串比較。

示例:

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

region_code
類型 字串
說明

發出要求的國家/地區或區域的 ISO 3166-1 alpha-2 代碼。如果無法判斷區域代碼,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
類型 布林值
說明

2SV 會使用軟體金鑰 (例如手機) 做為安全金鑰。

示例:

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 Authenticator 和備用碼) 進行驗證。

示例:

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 物件支援的屬性。如果找不到與要求中 ID 相關聯的裝置,則系統會將下列所有屬性評估為錯誤。

屬性
encryption_status
類型 enum
說明

說明裝置的加密狀態。

列舉值:

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
說明

指出裝置使用的作業系統。

列舉值:

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
類型 map<string, Vendor> vendors;
說明

vendors 物件用於存取第三方安全性和端點管理供應商提供的資料。每個供應商都可能填入三個共用頂層屬性:is_compliant_deviceis_managed_devicedevice_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

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
類型 布林值
說明

要求是否來自搭載已驗證的 ChromeOS 的裝置。

示例:

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.(string) -> boolean
說明

檢查裝置作業系統是否至少為指定版本。建議您搭配 device.os_type 屬性使用這個函式。

示例:

device.versionAtLeast("10.0") == true

certificateBindingState(origin, device)
類型 (Peer, 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) -> 布林值
說明

測試字串運算元是否以前置字元引數開頭。

示例:

"Sample string".startsWith("Sample")

endsWith()
類型 string.(string) -> 布林值
說明

測試字串運算元是否以後置字串引數結尾。

示例:

"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 的鍵。此處的 xp 中要使用的 ID,會繫結至元素或鍵。all() 巨集會結合每個元素的述詞結果和 and (&&) 運算子,因此如果任何述詞的評估結果為 false,巨集也會評估為 false,並忽略其他述詞的任何錯誤。示例:

這會傳回 false,因為並非所有元素都大於 1:
[1,2,3].all(x, x > 1)

e.exists(x, p) all() 巨集類似,但會結合述詞結果和 or (||) 運算子。範例:

因為清單中至少有一個元素大於 1,因此會傳回 true:
[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 擴充功能函式會判斷在要求時提供的憑證是否與裝置註冊端點驗證時註冊的任一裝置憑證相符。