跳到主要内容

配置 SAML 断言属性

SAML 属性是 SAML 断言中的关键组成部分，承载着经过认证 (Authentication) 用户的具体信息。这些属性可以包括用户标识符、角色 (Roles)、权限 (Permissions) 以及服务提供方 (SP) 进行授权 (Authorization) 和个性化所需的其他相关用户数据。

理解 SAML 属性​

在 SAML 认证 (Authentication) 中：

  • 属性是包含用户信息的名称-值对
  • 它们被包含在从身份提供商 (Logto) 发送到服务提供商的 SAML 断言中
  • 它们帮助服务提供商做出关于用户访问和个性化的明智决策
SAML 应用属性映射

Logto 中的属性映射​

属性映射允许你定义 Logto 中的用户信息应如何映射到 SAML 断言中的特定属性。此映射确保你的服务提供商能够以期望的格式和属性名称接收到用户信息。

当你配置属性映射时：

  1. 你指定哪些来自 Logto 的用户属性应包含在 SAML 断言中
  2. 你定义服务提供商期望的自定义属性名称
  3. 映射后的属性会在认证 (Authentication) 过程中自动包含在 SAML 断言中

常用属性​

一些常用的 SAML 属性包括：

  • Sub（用户 ID）
  • Email
  • 组织 (Organizations)
  • Name
  • Preferred username

查看 Logto 可用的所有用户数据

通过正确配置属性映射，你可以确保服务提供商获得所有必要的用户信息，从而为你的用户提供适当的访问和个性化体验。

你可以使用属性映射设置，将 Logto 可用的所有用户信息映射到你的 SP 期望的属性上。

静态属性​

有些服务提供商期望某些属性对每个用户都具有相同的值，例如在服务提供商侧标识你账户或站点的 ID。静态属性是 Logto 在应用的每个 SAML 断言中添加的固定名称-值对，与映射的用户属性一起发送。

例如，NetSuite SuiteCommerce 集成可能需要 account 和 site 属性：

属性名称值
account你的 NetSuite 账户 ID
site你的网站 ID

在 Console 中配置静态属性​

  1. 前往 Console > 应用程序 并打开你的 SAML 应用。
  2. 打开 属性映射 标签页，在 基础属性映射 下方找到 静态属性 卡片。
  3. 在 Key 中输入属性名称，在 Value 中输入其值。点击 Add another 可添加更多属性。要移除最后一个属性，清空其 key 和 value 即可。
  4. 点击 保存更改。

通过 Management API 配置静态属性​

在使用 Management API 创建 或 更新 SAML 应用时设置 staticAttributes：

curl \
  --request PATCH \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{"staticAttributes": {"account": "<your-account-id>", "site": "<your-site-id>"}}' \
  'https://[tenant-id].logto.app/api/saml-applications/<application-id>'

包含 staticAttributes 的更新会替换整个对象，因此请包含你想保留的每个静态属性。省略该字段则保持不变，发送 {} 可移除所有静态属性。

静态属性规则​

  • 属性名称可包含 ASCII 字母、数字及 _ - . : / # @ 字符，因此如 http://schemas.example.com/claims/site 或 urn:oid:1.3.6.1.4.1.5923.1.1.1.6 这样的 URI 和 OID 名称是被接受的。
  • 每个静态属性必须有一个非空字符串值。
  • 名称不得彼此冲突，也不得与断言中的用户属性名称冲突：即属性映射中 应用程序的值名称 列的名称，或在未映射时的 sub、email 和 name。Logto 会在将名称转换为 camel case 后进行比较，.、_ 和 - 作为单词分隔符，因此 site_id、site.id 和 SiteId 会冲突，account 和 Account 也会冲突。更改属性映射时也会进行相同检查。如果保存时报冲突，请重命名其中一个属性。

断言中的所有属性（映射和静态）都使用 urn:oasis:names:tc:SAML:2.0:attrname-format:basic NameFormat，并作为 xs:string 值发送。如果你的服务提供商期望带有 urn:oasis:names:tc:SAML:2.0:attrname-format:uri NameFormat 的 URI 或 OID 名称，请确保它也接受 basic。