Configuring SAML 2.0 Artifact Binding¶
WSO2 Identity Server (WSO2 IS) supports acquiring SAML protocol messages via HTTP Artifact Binding according to section 3.5 of the SAML 2.0 core specification . Once a user is authenticated successfully, the WSO2 Identity Server issues a SAML artifact in the place of the actual SAML response. The service provider application can acquire this artifact and use it as a reference to obtain the actual SAML response from WSO2 Identity Server. The following sections guide you through configuring SAML artifact binding and trying it out with a sample application.
Click here for more information about artifact binding
You can use HTTP artifact binding for instances where the SAML requester and responder need to communicate with each other using an HTTP user agent as an intermediary, but it's limitations preclude or discourage the transmission of an entire message (or message exchange) through it. This may be due to some technical reasons or the reluctance to expose the message content to the intermediary (where encryption is not practical).
In the HTTP artifact binding, the SAML request, the SAML response, or both are transmitted by reference using a small stand-in called an artifact. A separate, synchronous binding, such as the SAML SOAP binding, is used to exchange the artifact for the actual protocol message using the artifact resolution protocol. When using the HTTP artifact binding for the SAML \<Response> message, SAML permits the artifact to be delivered via the browser using either an HTTP POST or HTTP Redirect response.
About SAML Artifact
SAML artifact is a short, opaque string which will have the ability of an artifact receiver to identify the issuer of the artifact, resistance to tampering and forgery, uniqueness, and compactness.
The format of a SAML artifact is shown below:
The diagram below shows the process of SAML Artifact Binding.
Setting up the samples¶
To try out the functionality using a sample application, you need to set up the PickUp Dispatch sample application. You can skip this section if you wish to try out the functionality with your own sample application or with an existing service provider.
Before you begin
Enable a SAML tracer on your browser to view the SAML response artifact.
Deploy and configure
Access the PickUp application URL at http://localhost:8080/saml2-web-app-pickup-dispatch.com.
Once you deploy the sample application and start the tomcat server, a folder named saml2-web-app-pickup-dispatch.com is created inside the
<TOMCAT_HOME>/webappsdirectory. Navigate to the
<TOMCAT_HOME>/webapps/saml2-web-app-pickup-dispatch.com/WEB-INF/classesfolder and open the
The following properties inside the sso.properties file are related to SAML2 artifact binding. You can configure them accordingly if required.
If you configure the properties, restart the Tomcat server for the changes to take effect.
Property Description Default Value SAML2.ArtifactResolveUrl This is the Artifact Resolution Endpoint of the identity provider (IdP) which the service provider uses to resolve artifacts. https://localhost:9443/samlartresolve SAML2.EnableArtifactResolveSigning When this property is set to true, the sample application signs the artifact resolve requests that are send to the IdP. true
Restart the Tomcat Server once properties are changed.
Configuring SAML artifact binding¶
In the previous section of this guide you have deployed and registered the
saml2-web-app-pickup-dispatchwebapp. Let's edit the same service provider to configure artifact binding.
Expand the Inbound Authentication configuration > SAML2 Web SSO configuration section, and click Edit.
Select Enable SAML2 Artifact Binding to enable SAML2 artifact binding. Once this is enabled, WSO2 Identity Server responds to each SAML SSO authentication request with an artifact.
You can also enable signature validation by selecting Enable Signature Validation in Artifact Resolve Request. Once this is enabled, WSO2 IS expects to receive signed artifact resolve requests and validates that signature against the service provider certificate. For more information, see the Resolving SAML2 artifacts with WSO2 IS section.
Leave the rest of the default configurations as it is and click Register.
Access the PickUp application URL: http://localhost:8080/saml2-web-app-pickup-dispatch.com.
Enter admin/admin credentials and click Login. Provide the required consent.
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://ServiceProvider.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 SAML2 artifacts and configuring an artifact expiration time.
Configuring artifact expiration time¶
According to the SAML 2.0 Binding
, 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 smaller than the SAML response validity period.
Resolving SAML2 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: https://wso2.is.com:9443/samlartresolve
The service provider 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 service
provider has to sign this request with it’s 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>