設定 SAML 屬性傳播

本頁說明如何啟用及使用安全宣告標記語言 (SAML) 屬性傳播功能。您可以使用這項功能，將身分識別提供者的 SAML 屬性套用至受 Identity-Aware Proxy (IAP) 保護的應用程式。傳播 SAML 屬性時，您可以指定要傳播的屬性，以及傳送屬性的方式。

事前準備

您應瞭解 SAML V2.0 聲明和通訊協定規格 (PDF)。

瞭解資料的處理方式

啟用 SAML 屬性傳播功能前，請務必瞭解Google Cloud 如何管理資料，以及您應該和不應該透過這個管道傳遞哪些類型的資訊。

您可以設定 IAP，在提供給受保護應用程式的資訊中加入一或多個屬性。如果您透過第三方識別資訊提供者設定單一登入 (SSO)，而識別資訊提供者的 SAML 聲明含有 <AttributeStatement>，Google Cloud 會暫時儲存與使用者 Google 帳戶工作階段相關聯的屬性。Google 帳戶工作階段到期後，非同步程序會在 1 週內永久移除資訊。您可以設定到期日。

請勿使用 SAML 屬性傳播功能傳播具敏感性的個人識別資訊 (PII)，例如帳戶憑證、身分證字號、持卡人資料、金融帳戶資料、醫療照護資訊或敏感背景資訊。

啟用 SAML 屬性傳播

在 Google Workspace 中建立單一登入 (SSO) 設定檔，然後使用 Google Cloud CLI 或 REST API 更新 IAP 設定，即可啟用 SAML 屬性傳播功能。

控制台

  1. 前往 Google Cloud 控制台的 IAP 頁面。
    前往 IAP
  2. 開啟資源的設定，然後捲動至「屬性傳播」。
  3. 選取「啟用屬性傳播」，然後按一下「儲存」。

  4. 在「SAML Attributes」分頁中，輸入要傳播的屬性，格式如下： attribute1, attribute2, attribute3

    您也可以使用自訂運算式輸入屬性。自訂運算式的屬性會顯示在「SAML 屬性」分頁中。如要在「SAML 屬性」分頁中顯示屬性，請務必使用下列運算式格式：
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. 在「要傳遞的憑證類型」部分，選取至少一個來自 IdP 的屬性格式，以傳遞至應用程式。

gcloud

執行下列 IAP gcloud CLI 指令，更新 SAML 屬性傳播設定：

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

更改下列內容：

  • FOLDER：應用程式所在的資料夾。
  • ORGANIZATION：應用程式所在的機構。
  • PROJECT：應用程式所在的專案。
  • RESOURCE_TYPE：資源類型。
  • SERVICE：服務。
  • VERSION：版本號碼。

YAML： 

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

JSON： 

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

REST API

如要設定要傳播的 SAML 屬性，請使用 IapSettings 中的 ApplicationSettings 物件，如下列範例所示：

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

設定輸出憑證

使用 SAML 屬性傳播時，您可以設定輸出憑證，透過多種媒介傳送屬性，包括 JSON Web Token (JWT) 和標頭。如要在 API 中設定憑證，可以指定以半形逗號分隔的字串清單，如下列範例所示：

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

使用一般運算語言篩選 SAML 屬性

您可以使用一般運算語言 (CEL) 函式篩選 SAML 屬性。

使用 CEL 運算式搭配 SAML 屬性傳播功能時，會受到下列限制：

  • 運算式必須傳回屬性清單。
  • 運算式最多可選取 45 個屬性。
  • 運算式字串不得超過 1,000 個字元。

使用 IAP SAML 屬性傳播功能時，系統支援下列 CEL 函式。

請注意，函式會區分大小寫，必須完全按照撰寫方式使用。串連函式呼叫時，strict 和 emitAs 函式的順序並不重要。

函式 範例 說明
選取欄位 a.b 從 proto a 選取欄位 b。字元 b 可以是另一個 proto、清單，或字串等簡單值類型。
篩選清單 list.Filter(iter_var, condition) 傳回 list 的子集，其中的項目符合 condition。
列出成員 「b」設定了「a」政策 如果值 a 是清單 b 的成員，則傳回 true。
selectByName list.selectByName("name") 從清單中選取要加入 name = "name" 的屬性。
附加 list.append(attribute) 將指定屬性附加至指定清單。
嚴格 attribute.strict() 使用 HEADERS 做為輸出憑證時，系統會發出不含 x-goog-iap-attr- 前置字元的屬性。
emitAs attribute.emitAs("new_name") 將指定屬性連同名稱 "new_name" 輸出至所有選取的輸出憑證。

CEL 運算式範例

假設 SAML 斷言：

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

如要選取 my_saml_attr_1，請使用下列 CEL 運算式：

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

如要選取 my_saml_attr_1 和 my_saml_attr_2，請使用下列 CEL 運算式：

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

屬性格式

所有選取的屬性都會完整複製到所有選取的輸出憑證。

範例：假設 SAML 判斷

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

JWT 和 RC 權杖

JWT 權杖會透過 additional_claims 欄位提供屬性。這個欄位是物件，包含屬性名稱與屬性值清單的對應。屬性名稱與提供的 SAML 判斷相同。

以範例 SAML 判斷來說，IAP JWT 包含下列項目：

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

SAML 聲明中的標頭

在標頭中，屬性、鍵和名稱的值會根據 RFC 3986 進行網址逸出，並以半形逗號連結。舉例來說，header&name: header$value 會變為 x-goog-iap-attr-header%26name: header%24value。

為確保 IAP 標頭的專屬性，每個標頭都包含 IAP 前置字串 x-goog-iap-attr-。基於安全考量，負載平衡器會移除任何前置字串為 x-goog-iap-attr 的要求標頭。這可確保應用程式收到的標頭是由 IAP 生成。

以範例 SAML 判斷來說，標頭如下所示：

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

以下範例說明 IAP 如何在標頭中傳播屬性時逸出特殊字元，例如 value&1、value$2 和 value,3：

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

以下是逸出標頭名稱的範例。

標頭名稱：

"iap,test,3": "iap_test3_value1,iap_test3_value2"

逸出標頭名稱：

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

自訂屬性

您可以使用 selectByName、append、strict 和 emitas 函式修改傳播的屬性名稱、指定是否要為某些屬性使用標頭前置字元，以及選取新的 IAP 提供的屬性。

如果不需要傳播 SAML 屬性，但需要 SM_USER 欄位中的電子郵件地址、裝置 ID 或時間戳記，可以從 iap_attributes list 中選取這些屬性：attributes.iap_attributes…

IAP 提供下列屬性：user_email、device_id 和 timestamp。

範例

下列範例說明如何使用 selectByName、append、strict 和 emitas 函式自訂屬性。

假設您有範例 SAML 斷言。

selectByName

使用 selectByName 函式，從指定清單中依名稱選取單一屬性。舉例來說，如要選取 my_saml_attr_1，請使用下列運算式：

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

使用 append 函式，將屬性附加至屬性清單。您必須從支援的應用程式內商品屬性清單中選取這項屬性。舉例來說，如要將 my_saml_attr_2 附加至含有 my_saml_attr_1 的清單，請使用下列運算式：

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

你最多可以新增 "my_saml_attr_2" 個篩選器。您也可以新增多個屬性，並透過串連附加項目將這些屬性附加至清單，如下所示：

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

搭配 strict 和 emitAs 功能使用時，附加單一屬性最實用。

strict

使用 strict 函式標記屬性，這樣 IAP 就不會為名稱加上 x-goog-iap-attr- 前置字元。如果後端應用程式必須使用確切的屬性名稱，這項功能就非常實用。範例：

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

使用 emitAs 函式指定屬性的新名稱。您指定的名稱會輸出至所有憑證。舉例來說，如要將 my_saml_attr_1 重新命名為 custom_name，請使用下列運算式：

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

您可以運用各種函式，針對特定用途自訂屬性。舉例來說，您可以使用下列運算式，從 IAP 屬性將使用者的電子郵件地址傳播為 "SM_USER"，以及其他 SAML 屬性：

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

輸出標頭如下所示：

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"

使用 SAML 屬性傳播時的限制

登入時，身分識別提供者傳送的屬性資料量上限為 2 KB 的 SAML 屬性資料。如果宣告超過 2 KB 上限，系統會拒絕，且登入會失敗。

大多數網路伺服器的要求大小上限為 8 KB。這會限制外送自訂屬性的大小，包括標頭中的重複屬性。如果屬性 (名稱加上值) 在重複編碼後的大小超過 5000 位元組，IAP 會拒絕要求並傳回 IAP 錯誤代碼 401。

在 SAML 屬性傳播中使用 Unicode 字元

這項功能不支援 Unicode 和 UTF-8 字元，因此屬性值必須是低 ASCII 字串。如果宣告不是低 ASCII，登入就會失敗。