SAML 2.0 对接文档

1. 系统角色说明

本 SSO 系统作为 SAML 2.0 身份提供者（IdP），负责用户认证并颁发身份断言。

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

2. 认证流程

用户 → 第三方应用(SP) → SSO 登录(IdP) → 用户认证 → 返回断言 → SP 创建会话

完整流程说明

用户访问第三方应用受保护资源

SP 检测到未登录，重定向到 SSO 登录页面，携带 TARGET 参数

用户在 SSO 完成身份认证

SSO 生成 SAMLart（票据），重定向回 SP

SP 使用 SAMLart 调用验证接口获取用户信息

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

3. 接口规范

3.1 登录页面

接口地址

GET {SSO_HOST}/cas/login?TARGET={回调地址}

请求参数

参数	类型	必填	说明
TARGET	String	是	SP 的回调地址，需进行 URL 编码

示例

响应

展示登录页面供用户输入凭证

登录成功后重定向到 TARGET，携带 SAMLart 参数

回调示例

https://app.example.com/saml/callback?SAMLart=ST-12345-xxxxx

3.2 断言验证接口

接口地址

GET {SSO_HOST}/cas/serviceValidate?SAMLart={票据}&TARGET={回调地址}

请求参数

参数	类型	必填	说明
SAMLart	String	是	登录成功后返回的票据
TARGET	String	是	SP 的回调地址（与登录时一致）

请求示例

成功响应

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

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" 
                 xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                 ID="_uuid" 
                 Version="2.0" 
                 IssueInstant="2026-01-16T10:00:00Z"
                 InResponseTo="https://app.example.com/saml/callback"
                 Destination="https://app.example.com/saml/callback">
  
  <saml2:Issuer>https://sso.example.com</saml2:Issuer>
  
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </saml2p:Status>
  
  <saml2:Assertion ID="_uuid" Version="2.0" IssueInstant="2026-01-16T10:00:00Z">
    <saml2:Issuer>https://sso.example.com</saml2:Issuer>
    
    <saml2:Subject>
      <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">用户ID</saml2:NameID>
      <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml2:SubjectConfirmationData 
          NotOnOrAfter="2026-01-16T10:05:00Z" 
          Recipient="https://app.example.com/saml/callback"
          InResponseTo="https://app.example.com/saml/callback"/>
      </saml2:SubjectConfirmation>
    </saml2:Subject>
    
    <saml2:Conditions 
      NotBefore="2026-01-16T10:00:00Z" 
      NotOnOrAfter="2026-01-16T10:05:00Z">
      <saml2:AudienceRestriction>
        <saml2:Audience>https://app.example.com/saml/callback</saml2:Audience>
      </saml2:AudienceRestriction>
    </saml2:Conditions>
    
    <saml2:AuthnStatement AuthnInstant="2026-01-16T10:00:00Z">
      <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:uri">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">zhangsan</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <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:uri">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">13800138000</saml2:AttributeValue>
      </saml2:Attribute>
      <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">zhangsan@example.com</saml2:AttributeValue>
      </saml2:Attribute>
    </saml2:AttributeStatement>
    
  </saml2:Assertion>
</saml2p:Response>

失败响应

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" 
                 xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                 ID="_uuid" 
                 Version="2.0" 
                 IssueInstant="2026-01-16T10:00:00Z">
  
  <saml2:Issuer>https://sso.example.com</saml2:Issuer>
  
  <saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:RequestDenied"/>
    <saml2p:StatusMessage>Ticket不存在</saml2p:StatusMessage>
  </saml2p:Status>
  
</saml2p:Response>

4. 用户信息提取

4.1 用户唯一标识

从 saml2:NameID 元素获取：

<saml2:NameID>zhangsan</saml2:NameID>

解析示例（Java）

4.2 用户属性

从 saml2:AttributeStatement 获取所有用户属性：

解析示例（Java）

4.3 标准属性列表

属性名	说明	示例
uid	用户唯一标识	zhangsan
name	用户姓名	张三
phone	手机号	13800138000
email	邮箱	zhangsan@example.com
employee_number	工号	20210001
type	用户类型	L01
auth_ip	认证IP	192.168.1.100

注：实际返回的属性由服务配置决定，可根据业务需求定制。

5. 服务配置

第三方应用需在 SSO 后台注册服务信息。

6.SAML 规范

项目	值
SAML 版本	2.0
协议命名空间	urn:oasis:names:tc:SAML:2.0:protocol
断言命名空间	urn:oasis:names:tc:SAML:2.0:assertion
SubjectConfirmation 方法	urn:oasis:names:tc:SAML:2.0:cm:bearer
NameID 格式	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
属性格式	urn:oasis:names:tc:SAML:2.0:attrname-format:uri

7. 错误码说明

状态码	说明	原因
Success	认证成功	-
RequestDenied	请求被拒绝	票据无效、已使用或不存在
Responder	响应错误	服务配置错误、权限不足

常见错误原因

Ticket不存在 - 票据已过期或从未生成

Ticket已经被使用过 - 票据重复使用（仅允许使用一次）

Service compare failed - TARGET 不在服务白名单中

IP access denied - 用户IP不在允许范围内

User access denied - 用户无访问该服务的权限

8. 测试方法

8.1 完整流程测试

步骤1：访问登录页面

步骤2：登录获取票据

在浏览器完成登录，系统会重定向到：

https://app.example.com/callback?SAMLart=ST-12345-xxxxx

步骤3：验证票据

8.2 常见测试场景

场景1：正常认证

访问登录页面 → 登录成功 → 获取票据 → 验证票据 → 获取用户信息

场景2：票据过期

使用超过10秒的票据 → 返回 "Ticket不存在"

场景3：票据重复使用

使用同一票据验证两次 → 第二次返回 "Ticket已经被使用过"

场景4：URL不匹配

使用未注册的 TARGET → 返回 "Service compare failed"

文档版本: v1.0
更新日期: 2026-01-16

1. 系统角色说明#

2. 认证流程#

完整流程说明#

3. 接口规范#

3.1 登录页面#

3.2 断言验证接口#

4. 用户信息提取#

4.1 用户唯一标识#

4.2 用户属性#

4.3 标准属性列表#

5. 服务配置#

6.SAML 规范#

7. 错误码说明#

8. 测试方法#

8.1 完整流程测试#

8.2 常见测试场景#