配置 SAML 属性传播

本页介绍了如何启用和使用安全断言标记语言 (SAML) 属性传播。您可以使用此功能来传播 SAML 从身份提供方向受 Identity-Aware Proxy (IAP)。传播 SAML 属性时， 您可以指定要传播的属性以及如何传递属性。

准备工作

如要使用 SAML 属性传播功能，您必须拥有 Chrome Enterprise Premium 许可。

您应了解 SAML V2.0 断言和协议规范。

了解数据处理方式

在启用 SAML 属性传播之前，请确保您了解如何 Google Cloud 负责管理数据，以及您应该提供哪些类型的信息 而不应越过此渠道。

您可以将 IAP 配置为在 以及向受保护的应用提供的信息。如果设置 通过第三方身份进行单点登录 provider 和 您的身份提供方在 SAML 断言中包含 <AttributeStatement>， Google Cloud 会临时存储与用户 Google 账号会话。当一个 Google 账号会话过期后， 流程会在一周内永久移除该信息。您可以配置 过期日期。

请勿将 SAML 属性传播用于敏感个人 个人身份信息 (PII)，例如账号凭据、由政府签发的身份证件 持卡人数据、财务账户数据、医疗保健信息或 敏感背景信息。

启用 SAML 属性传播

在 Google Workspace 中创建单点登录配置文件以启用 SAML 属性传播，然后更新 使用 Google Cloud CLI 或 REST API 更改 IAP 设置。

控制台

  1. 在 Google Cloud 控制台中，前往 IAP 页面。
    前往 IAP
  2. 打开资源的设置，然后滚动到属性传播。
  3. 选择启用属性传播，然后点击保存。

  4. 在 SAML Attributes（SAML 属性）标签页中，输入 使用以下格式进行传播： attribute1, attribute2, attribute3

    您也可以使用自定义表达式输入属性。 自定义表达式的属性都显示在 SAML 中 属性标签页。您必须使用以下表达式格式 SAML Attributes（SAML 属性）标签页中显示哪些属性：
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. 对于要传递的凭据类型，请至少选择一种属性格式 传递给应用。

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 令牌 (JWT) 和标头）发送属性。如需在 API 中设置凭据，您可以指定以英文逗号分隔的字符串列表，如以下示例所示：

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

使用通用表达式语言过滤 SAML 属性

您可以使用通用表达式语言 (CEL) 函数过滤 SAML 属性。

通过 SAML 属性传播使用 CEL 表达式具有以下限制：

  • 表达式必须返回属性列表。
  • 一个表达式最多可以选择 45 个属性。
  • 表达式字符串不能超过 1000 个字符。

以下是使用 IAP SAML 属性传播功能时支持的 CEL 函数。

请注意，这些函数区分大小写，使用时必须完全按照所编写的方式使用。在链接函数调用时，strict 和 emitAs 函数的顺序无关紧要。

函数 示例 说明
字段选择 a.b 从 proto a 中选择字段 b。字符 b 可以是其他 proto、列表或简单值类型，例如字符串。
过滤列表 list.Filter(iter_var, condition) 返回项满足 condition 的 list 的子集。
列表成员资格 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 属性传播，但需要电子邮件地址， 设备 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 属性传播时的限制

登录时，从身份提供方传入的属性不能超过 2KB SAML 属性数据超过 2KB 上限的断言将被拒绝， 登录失败。

大多数网络服务器的请求大小上限为 8KB。这会限制 传出自定义属性，包括标头中的重复属性。如果 在复制并且属性（名称加值）的大小超过 5000 字节时， 经过编码后，IAP 将拒绝请求并返回 IAP 错误代码 401。

SAML 属性传播涉及 Unicode 字符

此功能不支持 Unicode 和 UTF-8 字符，因此属性值必须为 低 ASCII 字符串。如果断言不是低 ASCII 值，则登录失败。