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

設定 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 屬性傳播功能

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

控制台

前往 Google Cloud 控制台的「應用程式內購」頁面。
前往 IAP
開啟資源的設定，然後捲動至「屬性傳播」。
選取「啟用屬性傳播」，然後按一下「儲存」。
在「SAML 屬性」分頁中，使用下列格式輸入要套用的屬性： attribute1, attribute2, attribute3

您也可以使用自訂運算式輸入屬性。自訂運算式的屬性會顯示在「SAML 屬性」分頁中。您必須使用下列運算式格式，才能在「SAML 屬性」分頁中顯示屬性：
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
針對「要傳遞的憑證類型」，請選取至少一個屬性格式，從 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 個屬性。
運算式字串不得超過 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)`	將指定屬性附加至指定清單。
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 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 函式，將屬性附加至屬性清單。您必須從支援的 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，登入作業就會失敗。