Use SAML 2.0 Artifact Binding¶
This page guides you through enabling SAML2 artifact binding with WSO2 Identity Server.
Generally, SAML authentication requests and assertion data is sent through the browser using POST or Http Redirect binding. If you do not want to expose the entire message to the browser, you can use artifact binding instead.
Register a service provider¶
Log in to the Management Console (
https://<IS_HOST>:<PORT>/carbon) using admin/admin credentials.
Navigate to Main > Identity > Service Providers and click Add.
saml2-web-app-pickup-dispatchin the Service Provider Name text box, and click Register.
In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.
Now set the configuration as follows:
Assertion Consumer URL :
Click Yes, in the message that appears.
Select the following check-boxes:
Enable Response Signing
Enable Single Logout
Enable Attribute Profile
Include Attributes in the Response Always
Enable Signature Validation in Authentication Requests and Logout Requests
Click Register to save the changes.
To configure more advanced configurations, see Advanced SAML Configurations.
Configure artifact expiration time¶
According to the SAML 2.0 Binding Specification, issued SAML Artifacts should have an expiration time. WSO2 Identity Server does not resolve the artifacts that have passed this time limit.
You can configure this restriction by adding the following property to the
[saml.artifact] validity= 4
The default time limit is 4 minutes. In a practical scenario, this time limit should be lesser than the SAML response validity period.
Resolve artifacts with WSO2 IS¶
According to the SAML Specification, issued SAML artifacts should be resolved, or exchanged to an actual SAML response, via a back-channel call to the issuer.
WSO2 Identity Server supports SOAP Binding to resolve SAML artifacts according to Section 3.6 of the SAML 2.0 Binding Specification.
WSO2 IS Artifact Resolution Endpoint:
The application should send an
<ArtifactResolve> message wrapped in a SOAP envelope to the WSO2 Identity Server artifact resolution endpoint. The following example shows a SAML artifact resolve request.
POST /samlartresolve HTTP/1.1 Host: wso2is.com Content-Type: text/xml Content-Length: nnn SOAPAction: http://www.oasis-open.org/committees/security <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <samlp:ArtifactResolve xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_6c3a4f8b9c2d" Version="2.0" IssueInstant="2004-01-21T19:00:49Z"> <Issuer>https://ServiceProvider.com/SAML</Issuer> <Artifact> AAQAADWNEw5VT47wcO4zX/iEzMmFQvGknDfws2ZtqSGdkNSbsW1cmVR0bzU= </Artifact> </samlp:ArtifactResolve> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
If signature validation for artifact resolve is enabled, the application has to sign this request with its private key. WSO2 IS validates the request and if it is valid, an
<ArtifactResponse> message is sent with the actual SAML response set as the message element. The code block below shows an example of an
HTTP/1.1 200 OK Date: 21 Jan 2004 07:00:49 GMT Content-Type: text/xml Content-Length: nnnn <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <samlp:ArtifactResponse xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_FQvGknDfws2Z" Version="2.0" InResponseTo="_6c3a4f8b9c2d" IssueInstant="2004-01-21T19:00:49Z"> <Issuer>https://wso2is.com</Issuer> <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </samlp:Status> <samlp:Response ID="d2b7c388cec36fa7c39c28fd298644a8" IssueInstant="2004-01-21T19:00:49Z" Version="2.0"> ... </samlp:Response> </samlp:ArtifactResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Set up the sample¶
Download Apache Tomcat 8.x from here and install. Tomcat server installation location will be referred as
<TOMCAT_HOME>later in this guide.
It is recommended that you use a hostname that is not
localhostto avoid browser errors. Modify the
/etc/hostsentry in your machine to reflect this. Note that
wso2is.localis used in this documentation as an example, but you must modify this when configuring the authenticators or connectors with this sample application.
saml2-web-app-pickup-dispatch.com.warfile from the latest release assets.
SAML2 POST Binding requires CORS configurations to be set up.
Before configuring the service provider, add the following configurations to the
deployment.toml file found in
<IS_HOME>/repository/conf/. Adding this configuration allows
HTTP POST requests.
``` toml [cors] allow_generic_http_requests = true allow_any_origin = false allowed_origins = [ "http://localhost:8080" ] allow_subdomains = false supported_methods = [ "GET", "POST", "HEAD", "OPTIONS" ] support_any_header = true supported_headers =  exposed_headers =  supports_credentials = true max_age = 3600 tag_requests = false ```
Deploy the sample¶
Deploy this sample web app on a web container.
saml2-web-app-pickup-dispatch.com.warfile into the
Start the Tomcat server.
Try artifact binding¶
Access the application application URL: http://wso2is.local:8080/saml2-web-app-pickup-dispatch.com.
You will be redirected to the login page of WSO2 IS. Log in using your WSO2 IS credentials (admin/admin). Provide the required consent. You will be redirected to the Pickup Dispatch application home page.
You can use a SAML tracer add-on with your browser to view the SAML2 response artifact for the SSO authentication request. The code block below shows an example response.
HTTP/1.1 302 Object Moved Date: 21 Jan 2004 07:00:49 GMT Location: https://application.com/ACS/URL? SAMLart=AAQAADWNEw5VT47wcO4zX%2FiEzMmFQvGknDfws2ZtqSGdkNSbsW1cmVR0bzU%3D&RelayState=0043bfc1bc45110dae17004005b13a2b Content-Type: text/html; charset=iso-8859-1
You have successfully set up SAML artifact binding. See the sections below for more information on resolving SAML 2.0 artifacts and configuring an artifact expiration time.