简化开发者的 SAML 认证集成

单点登录（SSO） 是现代应用的关键，SAML 能为企业身份系统之间提供安全、友好的认证体验。本指南为开发者和设计师简化了 SAML，通过清晰的步骤和实际示例，帮助你高效实现 SAML。

什么是 SAML 认证与 SAML 应用？#

安全断言标记语言（SAML） 是一种基于 XML 的标准，用于在两个核心角色之间交换认证和授权数据：身份提供者（IdP） 和 服务提供者（SP）。它是企业组织实现单点登录（SSO）的常见方案，让企业用户只需登录一次，就能访问多个应用。

身份提供者（IdP） 负责管理和验证用户凭证，比如用户名和密码。当用户尝试访问受保护的服务时，IdP 会确认用户身份并把这个确认信息发送给服务。

• 示例： 假设你在一家大型公司工作，公司使用 Microsoft Azure AD 管理员工账号。当你想登录 Salesforce 时，Azure AD 就是 IdP。它会检查你的凭证，然后告诉 Salesforce 你可以使用该服务。

服务提供者（SP） 是用户实际想要访问的应用或服务。它依赖 IdP 负责主要的身份认证工作。

• 示例： 接着上面场景，Salesforce 就是 SP。它依赖 Microsoft Azure AD（IdP）来确认你的身份。一旦 Azure AD 保证了你，Salesforce 就允许你访问。

在说到“SAML 应用”时，人们通常是指 SP。

使用 SAML 协议，你可以将服务设置为 IdP，支持应用集成（如 Azure AD / Google Workspace）；也可作为 SP（如 Salesforce / Slack），为用户提供 SSO。

SAML Assertion（断言） 是 SAML 协议的核心。它是由 IdP 生成并发送给 SP 的数字“凭证”，意思是“我已经确认了这个用户的身份”。接下来我们会介绍 IdP 和 SP 的工作流程。

作为 SAML 身份提供者时#

当你的服务作为 IdP 时，你可以为多个应用提供 SAML 认证，用户可通过一个企业身份访问不同服务。

这是 IdP 身份下典型的 SAML SSO 流程：

1. 用户尝试访问一个应用（SP），比如 Salesforce。
2. 应用将用户重定向到你的 IdP 进行认证。
3. 用户在你的 IdP 登录页面输入凭证。
4. IdP 校验凭证。
5. 如果验证通过，IdP 把 SAML 断言发送回 SP。
6. SP 处理断言，确认有效后授予用户访问权限。

作为 SAML 服务提供者时#

如果你的服务作为 SP，将与多种身份提供者集成，为用户提供 SSO 能力，使来自不同组织或租户的企业用户可以安全高效地访问你的应用。

这是 SP 发起的 SSO 流程：

1. 用户尝试登录你的应用。
2. 你的应用生成 SAML 请求并将用户重定向到 IdP 的登录页面。
3. 用户在 IdP 登录（如果已登录则跳过）。
4. IdP 验证用户身份，并在确认后将用户信息打包进 SAML 断言里。
5. IdP 把断言返回你的应用。
6. 你的服务校验断言，若验证通过，用户即可访问你的应用。

SAML SSO 关键参数#

要成功集成 SAML SSO，IdP 和 SP 必须共享一些特定参数，以下为必需项：

来自 IdP 的参数#

1. IdP 实体 ID：SAML 通信中区别 IdP 的唯一标识，相当于数字“名牌”。
2. SSO URL：SP 重定向用户登录认证的端点地址（URL）。
3. X.509 证书：用于签名 SAML 断言的公钥，保证断言安全。它就像验证真实性的“印章”。

提示：如果你的 IdP 提供了SAML 元数据 URL，会变得更轻松。该 URL 包含所有必需信息（如证书、SSO URL 和 IdP 实体 ID），可避免手动复制出错，也省去了手动更新证书文件的麻烦。

来自 SP 的参数#

1. SP 实体 ID：SP 的唯一标识，功能类似 IdP 实体 ID。
2. Assertion Consumer Service (ACS) URL：SP 期望 IdP 发送 SAML 断言的端点地址。
3. RelayState（可选）：在 SAML 过程中传递数据，如用户最初要访问的 URL。

SAML 属性映射和加密#

1. NameID 格式：定义用户标识符的类型（如邮箱地址、用户名等）。
2. SAML 属性：IdP 向 SP 发送的其他用户详情，比如角色、邮箱、部门。
   • 示例：如果 IdP 签名的 SAML 断言包含 email（[email protected]）、role（admin）、department（engineering），SP 可用 role 分配管理员权限，用 department 把用户分组进对应团队。为获取这些必需的用户数据，IdP 和 SP 需约定如何映射属性。例如，IdP 定义“department”为 team，SP 期待其为 group，正确映射才能确保顺畅的通信。
3. 加密断言（可选）：为保护认证敏感数据，SAML 断言可以加密。
   • IdP 的角色： 使用 SP 的公钥加密断言。
   • SP 的角色： 用私钥解密断言，获取用户详情。

至此，你已拥有建立 SAML 连接所需信息。要集成 Salesforce（SP）和 Azure AD（IdP），可按以下步骤操作：

• 从 Azure AD 获取 IdP 实体 ID、SSO URL 和证书，并配置到 Salesforce。
• 向 Azure AD 提供 Salesforce 的 SP 实体 ID 和 ACS URL。

Logto 让 SAML 集成变简单#

Logto 可作为 IdP 或 SP，支持你的应用实现 SAML SSO。

Logto 作为 SAML IdP 使用#

Logto 可为其他应用提供联合身份认证，并支持 多因素认证（MFA） 增强安全性。

1. 创建 Logto 应用 进入 Logto 控制台 > 应用 并创建新的 SAML 应用。
2. 配置 SAML 参数 用服务提供者（SP）的 Assertion Consumer Service URL 和 SP 实体 ID 设置应用。
3. 提供元数据 URL Logto 提供 IdP 元数据 URL，SP 可用其自动获取关键信息，如 SSO URL 和证书。
4. 高级配置（可选）
   • 你可以创建多个新证书（有指纹及过期时间），但同一时间只允许启用一个证书。
   • 修改 Name ID 格式 满足业务需求。
   • 通过复制粘贴服务提供者的 x509 证书，实现 SAML 断言加密。
5. 属性映射（可选） 可自定义用户属性如何与 SP 共享。

详细指导请参见官方文档：SAML 应用

Logto 作为 SAML SP 使用#

Logto 也支持通过 SAML 或 OIDC 协议集成任意企业 IdP。无论启用 SP 发起的 SSO 统一登录，还是配置 IdP 发起 SSO，操作都很直接。

1. 创建企业连接器 进入 Logto 控制台 > 企业 SSO 创建新的企业连接器，选择 SAML 作为协议标准。
2. 配置 SAML 参数 填写来自 IdP 的 元数据 URL 或 元数据 XML 文件。若无元数据，可切换至手动配置：输入 IdP 实体 ID、SSO URL，上传签名证书。
3. 提供 ACS URL 和 SP 实体 ID 将 Logto 的 ACS URL 和 SP 实体 ID 提供给 IdP，完成集成设置。
4. 属性映射（可选） 配置用户数据映射，如邮箱、姓名，确保信息在 IdP 与 Logto 之间正确传递。
5. 添加企业邮箱域名 在企业连接器的 “SSO 体验” 标签下，添加一个或多个邮箱域，确保只有指定域名的用户可通过 SSO 认证。
6. 启用 IdP 发起 SSO（可选） 仅在你的企业客户需要时启用该选项。此功能允许用户直接从 IdP 控制台登录你的应用。

详细指导可参见官方文档：企业 SSO 文档。

总结#

SAML 提供了标准化、安全的 SSO 方式，让认证更加顺畅。Logto 简化了 SAML 部署，无论你作为 IdP 还是 SP。其界面友好，同时支持 云端 和 开源 版本，让 SAML 集成不再复杂。只需配置少量参数，就可以将你的服务连接到任意 SAML IdP 或 SP，专注为用户打造更好的体验。