本页面介绍如何启用和使用安全断言标记语言 (SAML) 属性传播。您可以使用此功能将 SAML 属性从身份提供方传播到受 Identity-Aware Proxy (IAP) 保护的应用。传播 SAML 特性时,您可以指定要传播的特性以及传送特性的方式。
准备工作
您必须拥有 BeyondCorp Enterprise 许可,才能使用 SAML 特性传播功能。
您应了解 SAML V2.0 断言和协议规范。
了解数据的处理方式
在启用 SAML 特性传播之前,请确保您了解 Google Cloud 管理数据的方式,以及您应该和不应通过此渠道传递哪些类型的信息。
您可以将 IAP 配置为在它提供给受保护应用的信息中包含一个或多个属性。如果您通过第三方身份提供方设置单点登录,并且您的身份提供方在 SAML 断言中包含 <AttributeStatement>
,则 Google Cloud 会暂时存储与用户的 Google 帐号会话关联的特性。Google 帐号会话到期后,异步流程会在一周内永久移除相应信息。您可以配置失效日期。
请勿将 SAML 属性传播用于敏感的个人身份信息 (PII),如帐号凭据、政府身份证号码、持卡人数据、财务账户数据、医疗保健信息或敏感的背景信息。
启用 SAML 特性传播
在 Google Workspace 中创建单点登录配置文件以启用 SAML 特性传播,然后使用 Google Cloud CLI 或 REST API 更新 IAP 设置。
控制台
- 在 Google Cloud 控制台中,转到 IAP 页面。
前往 IAP - 打开资源的设置,然后滚动到属性传播。
- 选择启用属性传播,然后点击保存。
在 SAML Attributes 标签页中,使用以下格式输入要传播的属性:
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 令牌 (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" 属性。 |
append | 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 属性数据上限为 2KB。超过 2 KB 的断言将被拒绝,登录失败。
大多数网络服务器的请求大小限制为 8KB。这会限制传出自定义属性的大小,包括标头中的重复属性。如果属性(名称加值)的大小在复制和编码时超过 5000 个字节,则 IAP 会拒绝请求并返回 IAP 错误代码 401。
SAML 属性传播中的 Unicode 字符
此功能不支持 Unicode 和 UTF-8 字符,因此属性值必须是低 ASCII 字符串。如果断言不是低 ASCII 值,则登录失败。