竹云IDaaS•开放平台

SAML2.0简介

最后更新时间: 1/19/2024, 6:04:34 PM

SAML全称是安全断言标记语言（Security Assertion Markup Language），是OASIS安全服务技术委员会的一个产品，是一个基于XML的开源标准数据格式，SAML解决的最重要的需求是Web端应用系统的单点登录（SSO），在不同的安全域(security domain)之间交换认证和授权数据。

本文档描述第三方应用如何使用SAML协议集成竹云IDaaS统一认证的步骤方法，为进行统一认证集成的应用开发人员提供参考指导。

# SAML认证流程

# IDP发起SSO

图片来源OASIS: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html (opens new window)

  1. Idp进行安全上下文检查，检查用户登录会话是否失效。

  2. 若用户会话失效，则需要用户重新登录。

  3. 用户选择 IdP 上的菜单选项或链接以请求访问 SP 网站 。 并且调用 IdP 的单点登录服务。

  4. Idp的单点登录服务开始构建SamlResponse生成断言 并通过Post 表单返回断言到sp的ACS接口。

  5. SP的ACS接口接收SamlResponse，首先验证断言上的数字签名，然后处理断言内容，并在sp中创建用户会话。

  6. 根据用户权限对其开放资源。

# SP发起SSO

图片来源OASIS:http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html (opens new window)

  1. 用户访问SP中的服务。

  2. SP发起一个Redirect/Post 请求并带上SAMLRequest 到IDP的SSO接口。

  3. Idp进行安全上下文检查，确认用户是否在IDP出满足登录条件、不满足则进行登录；若用户在IDP未能则进行登录。

  4. IDP的SSO接口通过SAMLRequest和当前的用户信息构建一个SAMLResponse。

  5. IDP将组装好的SAMLResponse 通过Post请求返回到SP的ACS接口。

  6. SP的ACS接口接收SamlResponse，首先验证断言上的数字签名，然后处理断言内容，并在sp中创建用户会话，并根据用户权限对其开放资源。

# 开发步骤

# IDP发起单点登录

用户登录IDaaS系统后通过此接口可以直接访问应用。此时浏览器会先调用IDP的SSO接口并返回SAMLResponse。

# 请求说明

GET https://{your_domain}/api/v1/saml2/idp/sso

# 请求参数

参数名 中文名称 必须 描述
sp sp的entityId 必须 此值为sp的entityId

# 请求示例

GET https://xxxx/api/v1/saml2/idp/sso?sp={sp entity id}

# 返回参数

认证通过后，IDP将响应断言SAMLlResponse通过Post请求返回给SP ACS地址，SP端通过解析响应断言后，获取到当前登录用户的信息。

# 返回示例

返回标准的SAMLResponse.xml

# SP发起单点登录

用户从SP的系统发起认证请求到IDP,该请求会携带SP的SAMLRequest，IDP接收请求后完成用户登录流程后生成断言，并返回响应断言SAMLResponse。

# 请求说明

POST/GET https://{your_domain}/api/v1/saml2/idp/sso

# 请求参数

参数名 中文名称 必须 描述
SAMLRequest Saml请求 必须 内容为SAMLRequest
RelayState State校验值 必须 IDP回调acs时需要带上该参数用与校验一致性

# POST请求示例

Form表单封装 SAMLRequest及RelayState参数

SAMLRequest: 为标准的SAMLRequest格式内容

# GET请求示例

GET https://{your_domain}/api/v1/saml2/idp/sso?RelayState=0a13c8ab-0398-4055-aa50-732d9d698283&SAMLRequest=jVLLjtsgFP0Vi70Nxo6ToDijNFHUSNNONPbMYjYVxmQGFYPLxWn79yV2I6WbqCxYwHlcnXNXD786HZ2lA2VNidKEoEgaYVtl3kv0Uu/jBXpYr4B3umebwX+YZ/ljkOCjwDPAxo8SDc4wy0EBM7yTwLxg1ebLI6MJYb2z3gqrUbQBkM4Ho601MHTSVdKdlZAvz48l+vC+B4bx9w6ShneNtULboU2E7XCvh3dlAAf6WUuPL66Yh2lQtAuzKMP9OP5VoxFJIwQHr+XI573CvIOJp9oeV9UT5lpxwJSkS7IkNCXZjJBlkcfzTbhyui12y2K/RdFhV6JvheAzeaKn2Vye8iacBSGiECmd01ws2iLAAAZ5MOC58SWihNKYZHGa1oSyfMmyLJlnizcUHf/G8UmZKeR72TUTCNjnuj7Gx6eqRtHrtawAQFM1bDR3N53cl+XXItD6TuwrfKM9GdGefQ1qh93RaiV+3xjS/98Cre3PrZPcyxJ5N0gU7a3ruL8vcHlRbXwaoay/hABeGo/wehr03/1c/wE=
1

# 返回参数

返回标准的SAMLResponse.xml

# 获取IDP元数据接口

通过获取IDPMetadata接口 获取IDP的元数据用于在SP系统设置IDP的相关配置。

# 请求说明

GET https://{your_domain}/api/v1/saml2/idp/metadata

# 请求参数

无

# 请求示例

https://lxsamlidp.idaas-test-alpha.bccastle.com/api/v1/saml2/idp/metadata

# 返回参数

返回当前企业的IDP Metadata.xml 文件

# SP发起的退出接口

该退出接口为IDP的退出接口，当sp端退出时可以调用该接口来退出idp的用户会话。

# 请求说明

POST/GET https://{your_domain}/api/v1/saml2/idp/logout

# 请求参数

参数名 中文名称 必须 描述
SAMLRequest saml请求xml 必须 内容为SAMLLogoutRequest

# POST请求示例

Form表单封装 SAMLRequest参数

SAMLRequest: 内容为标准的SAMLLogoutRequest格式

# GET请求示例

GET https://{your_domain}/api/v1/saml2/idp/logout?SAMLRequest=nZJLT8QgFIX/SsO+5RboY8h0jLExaaIufMW4MZSiNrZQe6mZny8z4yTqwoULCAHOd3IOrE+24xB9mBl7ZyuSJkAiY7XrevtSkbvb87gkJ5s1qnGY5IV7cYu/Nu+LQR8FoUW5P6nIMlvpFPYorRoNSq/lzenlhWQJyGl23mk3kKgOut4qv/d69X5CSWmrk1ZrhX4wiXYjVVNP1Yh0R6Z9N9Fhb0vV0CukDNIVrIClwDOAVS7i4jRMgp3l9So/PyNRU1fkqYSct0WmSugKkeuyFMzwTKiCcVY8Z0W4hriYxqJX1leEAWMx8DhNbyGXABLKhIvskUT3x25CFHJoQu6187cG/i5AIZp5F5psjqHfRkxaNbbO6cEt3S74mn5jfxldBVZT/8coULf9F/JAOb7ijcFdoMZ2Zrtp6gdu2rJ97iDmoc9YiLBqjSpipowuU2F4GAfQL+1x88e32HwC
1

# 返回参数

如果HTTP状态码为200则说明调用成功。

参数名 中文名称 必须 描述
SAMLResponse saml响应结果 必须 IDP返回的SAMLLogoutResponse

# 返回码

返回码 说明
invalid_request 非法请求
Unsupported binding 不支持的binding
AMS-0028 Saml属性配置错误
AMS-0029 Saml证书错误

# 术语说明

  • IDP：身份服务提供者(Identity Provide)是系统中的一个实体，用于确保用户真的是其所声称的身份——提供身份验证。身份提供者还负责确认系统中各实体上哪些服务可以被该用户访问。

  • SP：服务提供者(Service Provider)。

  • SSO：单点登录(SingleSignOn)，就是通过用户的一次性鉴别登录。用户只需一次登录就可以访问所有相互信任的应用系统。

  • IDP Metadata: 身份服务提供者的元数据，也就是IDaaS的元数据。

  • SP Metadata: 应用的元数据。

概述