本頁面由 Cloud Translation API 翻譯而成。

自訂存取層級規格

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

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

物件

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

物件
`origin`	包含可識別要求來源的屬性。
`request.auth`	包含可識別要求驗證和授權方面的屬性。
`request.time`	包含時間屬性，可用於根據時段、星期幾或特定日期範圍，限制資源存取權。
`levels`	包含定義對其他存取層級的依附關係的屬性。
`device`	包含描述要求來源裝置的屬性。

「`origin`」屬性

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

屬性

ip

類型 string

說明

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

警告：請勿將 origin.ip 與空字串比較。未定義要執行的操作。

範例：

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

region_code

類型 string

說明

發出要求的國家/地區的 ISO 3166-1 alpha-2 代碼。如果無法判斷區域碼，origin.region_code 會評估為錯誤。

警告：請勿將 origin.region_code 與空字串比較。未定義要執行的操作。

範例：

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

「`request.auth`」屬性

本節列出 request.auth 物件支援的屬性。

屬性

principal

類型 string, list(string)

說明

發出要求的專屬使用者 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

類型

boolean

說明

使用者已透過密碼驗證。

範例：

request.auth.claims.crd_str.pwd == true

claims.crd_str.push

類型

boolean

說明

使用者透過推播通知在行動裝置上完成驗證。

範例：

request.auth.claims.crd_str.push == true

claims.crd_str.sms

類型

boolean

說明

使用者透過簡訊或電話收到的驗證碼通過驗證。

範例：

request.auth.claims.crd_str.sms == true

claims.crd_str.swk

類型

boolean

說明

兩步驟驗證使用軟體金鑰 (例如手機) 做為安全金鑰。

範例：

request.auth.claims.crd_str.swk == true

claims.crd_str.hwk

類型

boolean

說明

兩步驟驗證使用硬體金鑰，例如 Google Titan 金鑰。

範例：

request.auth.claims.crd_str.hwk == true

claims.crd_str.otp

類型

boolean

說明

使用者透過一次性密碼方法 (Google Authenticator 和備用碼) 進行驗證。

範例：

request.auth.claims.crd_str.otp == true

claims.crd_str.mfa

類型

boolean

說明

使用者透過這個表格中的任何方法 (pwd 除外) 完成驗證。

範例：

request.auth.claims.crd_str.mfa == true

如要進一步瞭解憑證強度政策，請參閱「設定憑證強度政策」。

「`request.time`」屬性

本節列出 request.time 物件支援的屬性。

屬性

getFullYear()

類型 string

說明

擷取年份 (例如：2023)。

範例：

request.time.getFullYear("America/Los_Angeles") == 2024

getMonth()

類型 string

說明

擷取月份，從 0 (一月) 到 11 (十二月)。

範例：

request.time.getMonth("America/Los_Angeles") == 0 (1 月)

getDate()

類型 string

說明

擷取當月日期，範圍為 1 到 31。

範例：

request.time.getDate("America/Los_Angeles") == 1

getDayOfMonth()

類型 string

說明

擷取當月日期，範圍為 0 到 30 (0 代表第一天)。

範例：

request.time.getDayOfMonth("America/Los_Angeles") == 0 (當月 1 號)

getDayOfWeek()

類型 string

說明

擷取星期幾，從 0 (星期日) 到 6 (星期六)。

範例：

request.time.getDayOfWeek("America/Los_Angeles") == 1 (星期一)

getDayOfYear()

類型 string

說明

擷取一年中的第幾天，範圍為 0 到 365。

範例：

request.time.getDayOfYear("America/Los_Angeles") == 0 (1 月 1 日)

getHours()

類型 string

說明

擷取當天的小時，範圍從 0 (午夜) 到 23 (晚上 11 點)。

範例：

request.time.getHours("America/Los_Angeles") == 19 (晚上 7 點)

getMinutes()

類型 string

說明

擷取小時的分鐘數，範圍為 0 到 59。

範例：

request.time.getMinutes("America/Los_Angeles") == 30

`levels` 屬性

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

屬性

level name

類型 boolean

說明

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

類型

boolean

說明

裝置是否已通過網域管理員核准。

範例：

device.is_admin_approved_device == true

is_corp_owned_device

類型

boolean

說明

裝置是否為機構擁有。

範例：

device.is_corp_owned_device == true

is_secured_with_screenlock

類型

boolean

說明

裝置是否已啟用螢幕鎖定功能。

範例：

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_device、is_managed_device 和 device_health_score。

此外，供應商可能會提供自己的鍵和值，並使用 data 屬性參照這些鍵和值。data 屬性的可用鍵會因供應商而異。比較政策運算式中的鍵值時，請務必保持一致。舉例來說，如果您預期鍵值為字串或布林值，請確保在政策運算式中，將鍵值與字串或布林值進行比較。請注意，如果值是整數，您應在政策運算式中與雙精度數字比較。

如要參照裝置狀態，請使用 key-acme 格式，其中 acme 是機構的客戶 ID。你可以從 GET https://www.googleapis.com/admin/directory/v1/customers/my_customer網址取得客戶 ID。回應中的 ID 欄位包含以字母 C 開頭的客戶 ID。請使用字母 C 後方的字串 (不含字母 C) 做為客戶 ID。

列舉值：

// 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

注意： is_device_compromised 僅為範例，代表供應商定義的金鑰。

android_device_security.verified_boot

類型 boolean

說明

Android 驗證開機程序狀態是否為 green。

範例：

device.android_device_security.verified_boot == true

android_device_security.cts_profile_match

類型

boolean

說明

裝置是否通過 CTS 設定檔法規遵循。

範例：

device.android_device_security.cts_profile_match == true

android_device_security.verify_apps_enabled

類型

boolean

說明

裝置是否已啟用 Google Play 安全防護驗證應用程式。

範例：

device.android_device_security.verify_apps_enabled == true

android_device_security.has_potentially_harmful_apps

類型

boolean

說明

裝置上是否發現可能有害的應用程式。

範例：

device.android_device_security.has_potentially_harmful_apps == true

ios_device_security.is_device_jailbroken

類型

boolean

說明

iOS 裝置是否越獄解鎖。

範例：

device.ios_device_security.is_device_jailbroken == true

verified_chrome_os

類型

boolean

說明

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

範例：

device.verified_chrome_os == true

chrome.management_state

類型 string

說明

瀏覽器是否由正確網域下的企業管理 (瀏覽器層級或設定檔層級)。

如果政策是集中管理及推送，且受管理瀏覽器或設定檔的網域與伺服器端的預期網域相符，瀏覽器就會視為受管理。

以下是可用的 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

類型

string

說明

瀏覽器版本高於特定最低版本。

範例：

device.chrome.versionAtLeast("88.0.4321.44")

chrome.is_realtime_url_check_enabled

類型

boolean

說明

是否已啟用即時網址檢查連接器。

範例：

device.chrome.is_realtime_url_check_enabled == true | false

chrome.is_file_upload_analysis_enabled

類型

boolean

說明

是否已啟用檔案上傳分析連接器。

範例：

device.chrome.is_file_upload_analysis_enabled == true | false

chrome.is_file_download_analysis_enabled

類型

boolean

說明

是否已啟用檔案下載分析連接器？

範例：

device.chrome.is_file_download_analysis_enabled == true | false

chrome.is_bulk_data_entry_analysis_enabled

類型

boolean

說明

是否已啟用大量文字 (貼上) 分析連接器。

範例：

device.chrome.is_bulk_data_entry_analysis_enabled == true | false

chrome.is_security_event_analysis_enabled

類型

boolean

說明

是否已啟用安全性事件報告連接器。

範例：

device.chrome.is_security_event_analysis_enabled == true | false

函式

Access Context Manager 提供下列函式，可用於自訂存取層級的 CEL 運算式。

函式

inIpRange(address, [subnets])

類型

(string, list(string)) -< boolean

說明

檢查 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) -> integer

說明

檢查與來源相關聯的用戶端憑證是否與裝置相符，並回報狀態。

函式傳回的狀態可以是下列其中一種：

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) -> bool

說明

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

範例：

"Sample string".startsWith("Sample")

endsWith()

類型

string.(string) -> bool

說明

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

範例：

"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` 的鍵。這裡的 `x` 是要在 `p` 中使用的 ID，會繫結至元素或鍵。`all()` 巨集會結合每個元素的述詞結果和 `and` (&&) 運算子，因此如果任何述詞的評估結果為 false，巨集就會評估為 false，並忽略其他述詞的任何錯誤。範例：由於並非所有元素都大於 1，因此系統會傳回 false： `[1,2,3].all(x, x > 1)`
`e.exists(x, p)`	與 `all()` 巨集類似，但會結合述詞結果和 `or` (\|\|) 運算子。範例：這會傳回 true，因為清單中至少有一個元素大於 1： `[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，而任何述詞錯誤都會導致巨集引發錯誤。範例：這會傳回 false，因為有多個元素大於 1： `[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 擴充功能函式會判斷要求時提供的憑證，是否與裝置註冊端點驗證時註冊的裝置憑證相符。

自訂存取層級規格 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

物件

「origin」屬性

「request.auth」屬性

「request.time」屬性

levels 屬性

device 屬性

函式

CEL 運算式的巨集

CEL 運算式範例

範例 1

範例 2

範例 3

自訂存取層級規格

「`origin`」屬性

「`request.auth`」屬性

「`request.time`」屬性

`levels` 屬性

`device` 屬性