SAML 属性映射

默认情况下，Authany 在 SAML 断言中只包含 sub 字段。SAML 属性映射可以让您添加其他 UserInfo 字段，例如邮箱、手机号或姓名，从而让您的 SAML 服务提供方获取所需的用户数据。

您可以直接从用户资料中映射字段，也可以先通过 Go 文本模板转换后再写入断言。

属性映射的工作原理

每个映射包含两部分：

• 定义（Definition）：按名称声明一个 SAML 属性。它将成为断言中 <Attribute> 元素的 Name。
• 映射（Mapping）：设置该属性的值，值可以来自 UserInfo 字段，也可以来自文本模板。

启用 SAML 属性映射

前置条件

• 一个已启用 SAML 2.0 支持 的客户端应用。设置方法参见 通过 SAML 集成。

操作步骤

1. 打开 Authany 管理台，进入高级 > 编辑配置。
2. 在 saml.service_providers 下，通过 client_id 找到您的应用。
3. 在该服务提供方下添加一个 attributes 块，包含 definitions 和 mappings。可参考下面的示例。
4. 保存配置。

示例

在与您的 client_id 匹配的服务提供方下添加 attributes 块。保留已有字段（如 acs_urls、audience、nameid_format 等）不变，这些字段是在创建 SAML 应用时设置的。

saml:
  service_providers:
  - client_id: YOUR_CLIENT_ID
    # ...existing fields, leave as-is...
    attributes:
      definitions:
      - name: family_name
      - name: given_name
      - name: placeholder_email
      mappings:
      - from:
          user_profile:
            pointer: /given_name
        to:
          saml_attribute: given_name
      - from:
          user_profile:
            pointer: /family_name
        to:
          saml_attribute: family_name
      - from:
          text_template:
            template: '{{.preferred_username}}@example.com'
        to:
          saml_attribute: placeholder_email

该 attributes 块会为发给此服务提供方的每个 SAML 断言添加三个属性：family_name、given_name 和 placeholder_email。

配置参考

definitions

每一项声明一个 SAML 属性。

Field	Type	Required	Description
name	string	是	属性名称，用作断言中 <Attribute> 元素的 Name。
name_format	string	否	设置 NameFormat 属性。参见 SAML Core 2.7.3.1。
friendly_name	string	否	设置 FriendlyName 属性。

mappings

每个映射设置一个已声明属性的值，支持两种来源类型。

从用户资料字段映射

使用 JSON 指针引用 UserInfo 对象中的任意字段。

- from:
    user_profile:
      pointer: /email
  to:
    saml_attribute: email

Field	Description
from.user_profile.pointer	指向 UserInfo 字段的 JSON 指针，例如 /sub、/email、/phone_number、/preferred_username。
to.saml_attribute	目标 SAML 属性的名称，必须与 definitions 中声明的某一项一致。

SAML 值类型由 JSON 类型决定：字符串对应 xs:string，数字对应 xs:decimal，布尔值对应 xs:boolean，数组则会生成多个 <AttributeValue> 元素。

说明

由 pointer 引用的字段必须存在于 UserInfo 中。缺失的字段会生成一个没有 <AttributeValue> 的属性。

从文本模板映射

使用 Go 文本模板 来构建值。模板会以 UserInfo 对象作为上下文。

- from:
    text_template:
      template: '{{.preferred_username}}@example.com'
  to:
    saml_attribute: placeholder_email

输出始终会渲染为 xs:string。缺失的字段会渲染为空字符串。

注意

映射的顺序很重要。如果两个映射写入同一个 saml_attribute，后面的映射会覆盖前面的。