SAML2.0简介
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
Idp进行安全上下文检查，检查用户登录会话是否失效。
若用户会话失效，则需要用户重新登录。
用户选择 IdP 上的菜单选项或链接以请求访问 SP 网站 。 并且调用 IdP 的单点登录服务。
Idp的单点登录服务开始构建SamlResponse生成断言 并通过Post 表单返回断言到sp的ACS接口。
SP的ACS接口接收SamlResponse，首先验证断言上的数字签名，然后处理断言内容，并在sp中创建用户会话。
根据用户权限对其开放资源。
SP发起SSO
图片来源OASIS:http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
用户访问SP中的服务。
SP发起一个Redirect/Post 请求并带上SAMLRequest 到IDP的SSO接口。
Idp进行安全上下文检查，确认用户是否在IDP出满足登录条件、不满足则进行登录；若用户在IDP未能则进行登录。
IDP的SSO接口通过SAMLRequest和当前的用户信息构建一个SAMLResponse。
IDP将组装好的SAMLResponse 通过Post请求返回到SP的ACS接口。
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=返回参数
返回标准的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返回参数
如果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: 应用的元数据。