設定 SAML 屬性傳播

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

事前準備

您應熟悉 SAML V2.0 斷言和通訊協定規格 (PDF)。

瞭解資料處理方式

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

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

請勿將 SAML 屬性傳播功能用於具敏感性的個人識別資訊 (PII),例如帳戶憑證、政府核發的身分證件、持卡人資料、金融帳戶資料、醫療照護資訊或機密背景資訊。

啟用 SAML 屬性傳播

如要啟用 SAML 屬性傳播功能,請在 Google Workspace 中建立 SSO 設定檔,然後使用 Google Cloud CLI 或 REST API 更新 IAP 設定。

控制台

  1. 前往 Google Cloud 控制台的「IAP」頁面。
    前往 IAP

  2. 開啟資源的設定,然後捲動至「屬性傳播」。

  3. 選取「啟用屬性傳播」,然後按一下「儲存」。

  4. 在「SAML Attributes」(SAML 屬性) 分頁中,使用下列格式輸入要傳播的屬性: attribute1, attribute2, attribute3

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

  5. 在「Credential types to pass」(要傳遞的憑證類型) 部分,選取至少一個來自 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

您可以使用 IapSettings 中的 ApplicationSettings 物件,設定要傳播的 SAML 屬性,如以下範例所示:

{
 "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 項屬性。

  • 運算式字串不得超過 1000 個字元。

以下是使用 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) 將指定屬性附加至指定清單。
strict 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 清單中選取這些屬性: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 函式,將屬性附加至屬性清單。您必須從支援的 IAP 屬性清單中選取這項屬性。舉例來說,如要將 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 屬性傳播時的限制

登入時,來自識別資訊提供者的傳入屬性,其 SAML 屬性資料上限為 2 KB。超過 2 KB 上限的宣告會遭到拒絕,導致登入失敗。

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

SAML 屬性傳播中的 Unicode 字元

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