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.
The diagram below shows the process of SAML Artifact Binding.
Configuring SAML artifact binding
- Log in to the management console.
- Navigate to Service Providers > Add in the Main menu of the management console and add a new service provider called " saml2-web-app-dispatch.com ". For more information about configuring a service provider, see Adding and Configuring a Service Provider.
- Expand the Inbound Authentication configuration > SAML2 Web SSO configuration section, and click Configure.
- Fill in the following fields.
- Issuer: saml2-web-app-dispatch.com
- Assertion Consumer URL:
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.
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,
This tutorial demonstrates SAML2 artifact binding using localhost.com as the local domain.
etc/hostsfile in your machine, a dd the following entry, and restart your computer to map the localhost.com domain to your ip address.
To avoid any IP address conflicts, ensure that this is the only entry for this IP address in the /etc/hosts file.
Enable a SAML tracer on your browser to view the SAML response artifact.
Download the following saml2-web-app-dispatch.com.war file and paste it inside the
Restart the Tomcat server.
Once you deploy the sample application and start the tomcat server, a folder named saml2-web-app-dispatch.com is created inside the
<TOMCAT_HOME>/webappsdirectory. Navigate to the
<TOMCAT_HOME>/webapps/saml2-web-app-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.
Tip: 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. SAML2.EnableArtifactResolveSigning When this property is set to true, the sample application signs the artifact resolve requests that are send to the IdP. true
- Access the PickUp application URL: http://localhost.com:8080/saml2-web-app-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.
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 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 editing the
<IS_HOME>/repository/conf/identity/identity.xml file. Open the file in a text editor and search for the
Note: 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.
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.
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