SAML 2.0 统一身份认证对接文档（IdP）

适用对象：需要接入本统一身份认证平台的第三方应用系统（SP）
协议版本：SAML 2.0
文档版本：v2.0
更新日期：2026-02-02

1. 系统角色说明

本系统作为 SAML 2.0 身份提供者（IdP），为第三方应用提供统一身份认证服务。

角色	名称	职责
IdP	统一身份认证平台	认证用户身份，生成 SAML 断言
SP	第三方应用系统	接收断言，授权用户访问资源

2. 认证流程（SP-Initiated SSO）

用户 → SP → [SAML Request] → IdP 认证 → 用户登录 → [SAML Response] → SP 创建会话

完整流程说明（HTTP-POST 绑定）

用户访问 SP 受保护资源

SP 检测到未登录，生成 SAML AuthnRequest，通过 HTTP POST 发送到 IdP

用户在 IdP 登录页面完成身份认证（或检测到已登录）

IdP 生成 SAML Response（包含用户断言和数字签名），通过 HTTP POST 返回 SP

SP 验证签名和断言后创建本地会话

用户成功访问 SP 资源

3. 接口规范

3.1 IdP 元数据端点

接口地址

GET {IdP_HOST}/sso/saml2/metadata

用途：SP 配置 IdP 时需要提供元数据文件，包含：

IdP EntityID：IdP 的唯一标识符

SSO 服务端点：接收 SAML AuthnRequest 的 URL

签名证书（X.509）：用于验证 SAML Response 签名

重要提示：如果该端点不可访问，请联系管理员获取 metadata.xml 文件

3.2 SSO 认证端点（接收 SAML Request）

接口地址

POST {IdP_HOST}/sso/saml2/sso

请求方式：HTTP-POST 绑定

请求参数

参数	类型	必填	说明
SAMLRequest	String	是	Base64 编码的 SAML AuthnRequest（由 SP 自动生成）
RelayState	String	否	会话状态参数（由 SP 维护，IdP 需原样返回）

SAML Request 示例（Base64 解码后）

<saml2p:AuthnRequest 
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
    AssertionConsumerServiceURL="https://sp.example.com/saml/acs"
    Destination="https://idp.example.com/sso/saml2/sso"
    ID="_request_id"
    IssueInstant="2026-02-02T02:53:23.352Z"
    Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    https://sp.example.com/
  </saml2:Issuer>
  <saml2p:NameIDPolicy 
      AllowCreate="true" 
      Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
</saml2p:AuthnRequest>

关键字段说明：

AssertionConsumerServiceURL：SP 的 ACS 端点（接收 SAML Response 的 URL）

Issuer：SP 的 EntityID（SP 的唯一标识符）

NameIDPolicy Format：SP 要求的 NameID 格式（常见：transient、persistent、unspecified）

3.3 SAML Response 返回（HTTP-POST 绑定）

用户认证成功后，IdP 通过 自动提交的 HTML 表单 将 SAML Response 发送到 SP。

HTTP 响应格式

HTTP Status: 200
Content-Type: text/html; charset=UTF-8

SAML Response 结构（Base64 解码后，已包含 双签名）

<saml2p:Response 
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    ID="_response_id"
    Version="2.0"
    IssueInstant="2026-02-02T02:53:23Z"
    InResponseTo="_request_id"
    Destination="{SP_ACS_URL}">
  
  <saml2:Issuer>{IdP_EntityID}</saml2:Issuer>
  
  <!-- Response 层签名（必需） -->
  <ds:Signature>
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
      <ds:Reference URI="#_response_id">
        <ds:Transforms>
          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
        <ds:DigestValue>...</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>...</ds:SignatureValue>
    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>[证书内容]</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </ds:Signature>
  
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </saml2p:Status>
  
  <saml2:Assertion ID="_assertion_id" Version="2.0" IssueInstant="2026-02-02T02:53:23Z">
    <saml2:Issuer>{IdP_EntityID}</saml2:Issuer>
    
    <!-- Assertion 层签名（必需） -->
    <ds:Signature>
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
        <ds:Reference URI="#_assertion_id">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <ds:DigestValue>...</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>...</ds:SignatureValue>
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>[证书内容]</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </ds:Signature>
    
    <saml2:Subject>
      <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">user_id</saml2:NameID>
      <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData 
          InResponseTo="_request_id"
          NotOnOrAfter="2026-02-02T02:58:23Z"
          Recipient="{SP_ACS_URL}"/>
      </saml2:SubjectConfirmation>
    </saml2:Subject>
    
    <saml2:Conditions 
      NotBefore="2026-02-02T02:52:23Z" 
      NotOnOrAfter="2026-02-02T02:58:23Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>{SP_EntityID}</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
    
    <saml2:AuthnStatement AuthnInstant="2026-02-02T02:53:23Z" SessionIndex="_session_id">
      <saml2:AuthnContext>
        <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
      </saml2:AuthnContext>
    </saml2:AuthnStatement>
    
    <saml2:AttributeStatement>
      <saml2:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">zhangsan</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute FriendlyName="Name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">张三</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="phone" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">13800138000</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute FriendlyName="Email" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">zhangsan@example.com</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="employee_number" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">202101</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="type" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">L01</saml2:AttributeValue>
      </saml2:Attribute>
      <!-- 其他业务属性根据 SP 需求配置 -->
    </saml2:AttributeStatement>
  </saml2:Assertion>
</saml2p:Response>

认证失败响应

<saml2p:Response 
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_error_response_id"
    Version="2.0"
    IssueInstant="2026-02-02T02:53:23Z"
    InResponseTo="_request_id"
    Destination="{SP_ACS_URL}">
  
  <saml2:Issuer>{IdP_EntityID}</saml2:Issuer>
  
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed"/>
    <saml2p:StatusMessage>用户认证失败</saml2p:StatusMessage>
  </saml2p:Status>
</saml2p:Response>

4. 用户属性说明

4.1 标准属性列表

IdP 可返回的用户属性（实际返回内容根据 SP 配置决定）：

属性名	说明	示例	NameFormat
uid	用户唯一标识	zhangsan	basic
name	用户姓名	张三	basic
phone	手机号	13800138000	basic
email	邮箱	zhangsan@example.com	basic
employee_number	工号/学号	202101	basic
type	用户类型	L01（教师）/L02（学生）	basic
department	部门/院系	计算机学院	basic
ic_number	身份证号	110101199001011234	basic
auth_ip	认证IP	192.168.1.100	basic

4.2 属性配置方式

SP 注册时配置：在 IdP 后台为每个 SP 配置需要返回的属性列表

属性映射：支持将 IdP 内部字段映射为 SP 要求的属性名

格式规范：

NameFormat：urn:oasis:names:tc:SAML:2.0:attrname-format:basic

AttributeValue 类型：xsi:type="xs:string"

空值处理：返回空标签 <saml2:AttributeValue/>

5. 数字签名规范

5.1 签名覆盖范围

本 IdP 支持以下签名模式（可配置）：

双签名模式（推荐）：同时对 <saml2p:Response> 和 <saml2:Assertion> 签名

Response 签名：仅对 <saml2p:Response> 签名

Assertion 签名：仅对 <saml2:Assertion> 签名

5.2 签名算法

项目	算法标识符
签名算法	RSA-SHA256 (`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`)
摘要算法	SHA-256 (`http://www.w3.org/2001/04/xmlenc#sha256`)
规范化算法	Exclusive XML Canonicalization (`http://www.w3.org/2001/10/xml-exc-c14n#`)
Transform	Enveloped Signature + Exclusive C14N

5.3 证书管理

证书格式：X.509（嵌入在 <ds:X509Certificate> 中）

获取方式：从 IdP 元数据文件中获取公钥证书

证书更新：证书更新后需重新同步元数据到 SP

验证方式：SP 使用证书公钥验证 SAML Response 签名

6. SAML 协议规范

项目	值	说明
SAML 版本	2.0	固定值
协议命名空间	urn:oasis:names:tc:SAML:2.0:protocol	固定值
断言命名空间	urn:oasis:names:tc:SAML:2.0:assertion	固定值
绑定方式	HTTP-POST	推荐方式
SubjectConfirmation 方法	urn:oasis:names:tc:SAML:2.0:cm:bearer	浏览器 SSO
NameID 格式	transient / persistent / unspecified	可配置
属性格式	urn:oasis:names:tc:SAML:2.0:attrname-format:basic	默认格式
断言有效期	NotBefore（当前时间-1分钟）～ NotOnOrAfter（当前时间+5分钟）	可配置
SubjectConfirmationData 有效期	NotOnOrAfter（当前时间+5分钟）	可配置

7. SP 接入配置指南

7.1 SP 需要提供的信息

SP 在接入 IdP 时需要提供以下信息：

参数名称	说明	示例
SP EntityID	SP 的唯一标识符（通常是 URL）	`https://sp.example.com/`
ACS URL	接收 SAML Response 的端点	`https://sp.example.com/saml/acs`
服务名称	应用系统的中文名称	教务系统
需要的用户属性	属性名称列表	uid, name, email, phone
NameID Format	要求的 NameID 格式	transient / persistent

7.2 IdP 提供的配置信息

SP 配置 IdP 时需要使用以下信息：

参数名称	获取方式
IdP EntityID	从元数据文件中获取
SSO Service URL	从元数据文件中获取（SingleSignOnService 元素）
IdP 元数据文件	从 `{IdP_HOST}/sso/saml2/metadata` 下载
签名证书	嵌入在元数据文件的 KeyDescriptor 中

8. 常见问题排查

8.1 签名验证失败

可能原因：

证书不匹配：SP 配置的证书与 IdP 实际使用的证书不一致

解决方案：从 IdP 元数据获取最新证书并更新 SP 配置

签名算法不支持：SP 不支持 RSA-SHA256 签名算法

解决方案：确认 SP 支持的签名算法，联系管理员调整配置

Audience 不匹配：SAML Response 中的 Audience 与 SP EntityID 不一致

解决方案：确认 SP 提供的 EntityID 准确无误

时间偏差：服务器时间相差超过容忍范围（通常为 5 分钟）

解决方案：同步服务器时间（NTP）

8.2 其他常见错误

错误类型	原因	解决方案
AuthnFailed	用户认证失败	检查用户名密码、账号状态
RequestDenied	请求被拒绝	检查 SAML Request 格式、SP 是否已注册
Responder	IdP 内部错误	查看 IdP 日志，联系技术支持
属性缺失	SP 要求的属性未返回	检查 SP 属性配置，确认用户是否有该属性值

9. 测试方法

9.1 完整流程测试

步骤 1：SP 配置 IdP

从 IdP 获取元数据文件（{IdP_HOST}/sso/saml2/metadata）

在 SP 系统中配置 IdP 信息：

IdP EntityID

SSO Service URL

签名证书（从元数据中提取）

配置属性映射规则（将 SAML 属性映射到 SP 用户字段）

步骤 2：IdP 注册 SP

向 IdP 管理员提供 SP 信息（EntityID、ACS URL、服务名称）

配置 SP 需要的用户属性列表

配置访问控制策略（可选）

步骤 3：发起 SSO 测试

访问 SP 受保护资源

SP 自动重定向到 IdP 登录页面

完成用户认证（或检测到已登录）

自动跳转回 SP 并创建会话

验证用户信息是否正确

9.2 调试工具

SAML Tracer（浏览器插件）

推荐安装：Chrome/Firefox 扩展 "SAML-tracer"

功能：实时捕获 SAML Request 和 Response

用途：查看 Base64 解码后的 XML 内容，验证签名和属性

在线工具

SAML Developer Tools：Base64 编解码

XML Signature Validator：验证 XML 签名

SAML Metadata Generator：生成/验证元数据

10. 技术支持

10.1 联系方式

如遇到对接问题，请提供以下信息：

SP 基本信息：服务名称、EntityID、ACS URL

完整的 SAML Request（Base64 解码后的 XML）

完整的 SAML Response（Base64 解码后的 XML）

错误信息：SP 返回的错误码和错误描述

IdP 日志（时间范围：发生错误前后 5 分钟）

浏览器网络抓包（SAML-tracer 导出的 HAR 文件）

10.2 常用参考资料

SAML 2.0 技术概述

SAML 2.0 核心规范

SAML 2.0 绑定规范

文档版本：v2.0
协议版本：SAML 2.0
更新日期：2026-02-02
适用范围：所有支持 SAML 2.0 协议的 SP 系统

SAML 2.0 统一身份认证对接文档（IdP）

1. 系统角色说明#

2. 认证流程（SP-Initiated SSO）#

完整流程说明（HTTP-POST 绑定）#

3. 接口规范#

3.1 IdP 元数据端点#

3.2 SSO 认证端点（接收 SAML Request）#

3.3 SAML Response 返回（HTTP-POST 绑定）#

4. 用户属性说明#

4.1 标准属性列表#

4.2 属性配置方式#

5. 数字签名规范#

5.1 签名覆盖范围#

5.2 签名算法#

5.3 证书管理#

6. SAML 协议规范#

7. SP 接入配置指南#

7.1 SP 需要提供的信息#

7.2 IdP 提供的配置信息#

8. 常见问题排查#

8.1 签名验证失败#

8.2 其他常见错误#

9. 测试方法#

9.1 完整流程测试#

9.2 调试工具#

10. 技术支持#

10.1 联系方式#

10.2 常用参考资料#