Introduction to SAML 2.0
SAML stands for Security Assertion Markup Language. It is a product of the OASIS Security Services Technical Committee, an open standard data format based on XML. The most important need that SAML addresses is Single Sign-On (SSO) for web-based application systems, exchanging authentication and authorization data between different security domains.
This document describes the steps and methods for third-party applications to integrate with Zhuyun IDaaS unified authentication using the SAML protocol, providing reference guidance for application developers performing unified authentication integration.
# SAML Authentication Process
# IDP-Initiated SSO
Image source OASIS: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html (opens new window)
IdP performs a security context check to see if the user's login session has expired.
If the user session has expired, the user needs to log in again.
The user selects a menu option or link on the IdP to request access to the SP website. This calls the IdP's single sign-on service.
The IdP's single sign-on service begins constructing the SamlResponse, generates an assertion, and returns the assertion via a POST form to the SP's ACS interface.
The SP's ACS interface receives the SamlResponse, first verifies the digital signature on the assertion, then processes the assertion content, and creates a user session in the SP.
Resources are opened to the user based on their permissions.
# SP-Initiated SSO
Image source OASIS:http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html (opens new window)
The user accesses a service within the SP.
The SP initiates a Redirect/Post request carrying a SAMLRequest to the IDP's SSO interface.
The IdP performs a security context check to confirm if the user meets the login conditions at the IDP; if not, it proceeds with login. If the user cannot log in at the IDP, it proceeds with login.
The IDP's SSO interface constructs a SAMLResponse using the SAMLRequest and current user information.
The IDP returns the assembled SAMLResponse via a POST request to the SP's ACS interface.
The SP's ACS interface receives the SamlResponse, first verifies the digital signature on the assertion, then processes the assertion content, creates a user session in the SP, and opens resources to the user based on their permissions.
# Development Steps
# IDP-Initiated Single Sign-On
After logging into the IDaaS system, users can directly access the application through this interface. At this point, the browser will first call the IDP's SSO interface and return a SAMLResponse.
# Request Specification
GET https://{your_domain}/api/v1/saml2/idp/sso
# Request Parameters
| Parameter | Chinese Name | Required | Description |
|---|---|---|---|
| sp | SP's entityId | Required | This value is the SP's entityId |
# Request Example
GET https://xxxx/api/v1/saml2/idp/sso?sp={sp entity id}
# Response Parameters
After successful authentication, the IDP will send the assertion SAMLResponse via a POST request to the SP's ACS address. The SP side parses the response assertion to obtain the information of the currently logged-in user.
# Response Example
Returns a standard SAMLResponse.xml
# SP-Initiated Single Sign-On
Users initiate an authentication request from the SP's system to the IDP. This request carries the SP's SAMLRequest. After receiving the request, the IDP completes the user login process, generates an assertion, and returns the response assertion SAMLResponse.
# Request Description
POST/GET https://{your_domain}/api/v1/saml2/idp/sso
# Request Parameters
| Parameter Name | Chinese Name | Required | Description |
|---|---|---|---|
| SAMLRequest | SAML Request | Required | Content is SAMLRequest |
| RelayState | State Verification Value | Required | The IDP needs to include this parameter when calling back to ACS for consistency verification |
# POST Request Example
Form encapsulates the SAMLRequest and RelayState parameters.
SAMLRequest: Content in standard SAMLRequest format.
# GET Request Example
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=
# Return Parameters
Returns a standard SAMLResponse.xml
# Get IDP Metadata Interface
Obtain the IDP's metadata through the Get IDPMetadata interface for configuring the IDP in the SP system.
# Request Description
GET https://{your_domain}/api/v1/saml2/idp/metadata
# Request Parameters
None
# Request Example
https://lxsamlidp.idaas-test-alpha.bccastle.com/api/v1/saml2/idp/metadata
# Return Parameters
Returns the current enterprise's IDP Metadata.xml file
# SP-Initiated Logout Interface
This logout interface is the IDP's logout interface. It can be called by the SP side to log out the user session on the IDP.
# Request Description
POST/GET https://{your_domain}/api/v1/saml2/idp/logout
# Request Parameters
| Parameter Name | Chinese Name | Required | Description |
|---|---|---|---|
| SAMLRequest | SAML Request XML | Required | Content is a SAMLLogoutRequest |
# POST Request Example
Form encapsulates the SAMLRequest parameter
SAMLRequest: Content is in standard SAMLLogoutRequest format
# GET Request Example
GET https://{your_domain}/api/v1/saml2/idp/logout?SAMLRequest=nZJLT8QgFIX/SsO+5RboY8h0jLExaaIufMW4MZSiNrZQe6mZny8z4yTqwoULCAHOd3IOrE+24xB9mBl7ZyuSJkAiY7XrevtSkbvb87gkJ5s1qnGY5IV7cYu/Nu+LQR8FoUW5P6nIMlvpFPYorRoNSq/lzenlhWQJyGl23mk3kKgOut4qv/d69X5CSWmrk1ZrhX4wiXYjVVNP1Yh0R6Z9N9Fhb0vV0CukDNIVrIClwDOAVS7i4jRMgp3l9So/PyNRU1fkqYSct0WmSugKkeuyFMzwTKiCcVY8Z0W4hriYxqJX1leEAWMx8DhNbyGXABLKhIvskUT3x25CFHJoQu6187cG/i5AIZp5F5psjqHfRkxaNbbO6cEt3S74mn5jfxldBVZT/8coULf9F/JAOb7ijcFdoMZ2Zrtp6gdu2rJ97iDmoc9YiLBqjSpipowuU2F4GAfQL+1x88e32HwC
# Return Parameters
If the HTTP status code is 200, the call is successful.
| Parameter Name | Chinese Name | Required | Description |
|---|---|---|---|
| SAMLResponse | SAML Response Result | Required | SAMLLogoutResponse returned by the IDP |
# Response Codes
| Response Code | Description |
|---|---|
| invalid_request | Invalid request |
| Unsupported binding | Unsupported binding |
| AMS-0028 | SAML attribute configuration error |
| AMS-0029 | SAML certificate error |
# Terminology
IDP: Identity Provider (Identity Provider) is an entity within the system responsible for verifying that a user is indeed who they claim to be—providing authentication. The identity provider is also responsible for confirming which services on various entities within the system can be accessed by that user.
SP: Service Provider.
SSO: Single Sign-On (Single Sign-On) refers to logging in through a user's one-time authentication. Users only need to log in once to access all mutually trusted application systems.
IDP Metadata: The metadata of the identity service provider, which is the metadata of IDaaS.
SP Metadata: Application metadata.