In the WSO2 Enterprise Integrator, as well as the WSO2 API Manager, the samples are included. The WSO2 API Manager typically has one sample PizzaShack that you can easily deploy (I will cover this in a later blog). The Enterprise Integrator has a subdirectory of samples, which include numerous samples for both the Enterprise Integrator, Business Process Server and Data Services.
For the WSO2 Identity Server, historically, the samples have not been included. They’ve been available on GitHub and can be downloaded as I describe in this blog. However, for the latest version of the WSO2 Identity Server (5.11.0), the download procedure has changed. In this blog, I will describe the change procedure, and how you can download, build and use the samples that are with the WSO2 Identity Server.
Flavor of samples
The samples are available in two, I would say flavors. One of them, one I prefer to use, is the source code. The source code can be downloaded. And if you like you can do a checksum validation, to see whether the checksum that was calculated is also still the correct one.
There is also a compiled version available online. These are the individual war files that are defined and compiled. However, downloading them needs to be done individually. And I’d rather have the source code, as I previously stated. The latest compiled version is 4.3.0 and can be found with this link.
Downloading the samples
The samples can be found on GitHub. Here to be precise. This is the master branch.
You can clone the repository with Git but what you also can do is to simply download the zip file if you don’t have git installed and or configured. I’m using this script on Linux to download the samples and compile them. The tag v4.3.6 is the latest version available at the time of writing (July 2021) and is stated to be compatible with version 5.10.0 at least. I’m assuming it’s also compatible with 5.11. What the script does is download the sample and unpackage onto the desktop, open the folder and execute maven clean install command to build all the samples. This may take some time as the number of samples is quite big. The download is 100+ MB and on a 2 core AWS instance compilation took about 6:39 minutes. If all required dependencies are not present it can take up to 12+ minutes.
wget https://github.com/wso2/samples-is/archive/refs/tags/v4.3.6.zip -P /opt/wso2/Downloads
unzip /opt/wso2/Downloads/v4.3.6.zip -d /opt/wso2/Desktop
cd /opt/wso2/Desktop/samples-is-4.3.6
mvn clean installFor a maven build you need java and maven installed. If you do not have that, the compiled versions (see previous paragraph) are better. In the target directories you will find the war files that need to be deployed on for instance a Tomcat 8 server.
Working with one example
Now we need to work with the example. But which one? And how do we know how to use it? Luckily, there are a number of resources that we can take a look at. This is the README.md of the saml2-sso-sample.
The example allows Single Sign On between two sample apps. The samples of Identity Server are not so much running on the product but used to access functionality of the product. To get it up and running we need to do a couple of things (this is taken from the instructions mentioned above). I am not describing all steps to do this, since that would make the blog rather big.
Deploy the Identity Server 5.11.0 on a machine, create two service providers that will rely on Identity Server as the IDP and the SAML SSO process to allow single sign on.
The war files need to be deployed on a Tomcat 8 server. Luckily my training environment fits the requirements. Application distributions are named saml2-web-app-pickup-dispatch.com.war and saml2-web-app-pickup-manager.com.war respectively.
I have isolated the two war files and added them to Tomcat 8. I am doing this by dropping them in the webapps directory and verifying via the UI of Tomcat on localhost:8080.
Now we need to create two service providers as described in the documentation. Add a service provider and configure the Inbound Authentication Configuration – SAML2 WEB SSO Configuration.
Click Register and Go to Inbound Authentication Configuration. Configure the SAML2 setup.
Enter the values:
Issuer - saml2-web-app-pickup-dispatch.com
Assertion Consumer URLs - http://localhost.com:8080/saml2-web-app-pickup-dispatch.com/home.jsp Click on Add to add the value to the configuration.
Enable Response Signing and Single Logout, all other fields are empty. Click register to add. Click on Update to add another Service Provider.
Manager
Click Update to add another Service Provider. Call this one Manager.
Click Register and Go to Inbound Authentication Configuration. Configure the SAML2 setup.
Enter the values for manager application:
Issuer - saml2-web-app-pickup-manager.com
Assertion Consumer URLs - http://localhost.com:8080/saml2-web-app-pickup-manager.com/home.jspEnable Response Signing and Single Logout, all other fields are empty. Click register to add. Click on Update to return.
Deployment.toml
We need to enable CORS in the deployment.toml file. Add this to the deployment.toml file in [IS-HOME]/repository/conf
And restart the Identity Server for the changes to take effect. The toml file is only read at (re)start.
Trying out the sample
Access either of the URLs of the app http://localhost.com:8080/saml2-web-app-pickup-dispatch.com/ and http://localhost.com:8080/saml2-web-app-pickup-manager.com. Login with admin /admin credentials. See that when you are logged in on either, accessing the other app will bypass the login process due to the SAML2 assertion.
You login to Pickup:
With admin / admin credentials:
And are allowed in.
When you go to the Manager app and click on Login.
The SAML2 assertion is used to gain access.
Conclusion
The Identity Server has a number of nice examples to test or check out certain setups and are totally worth the download and build. Some of them are also available as ready war files as we mentioned before. Due to the nature of the Identity Server working with them is a little different (the Identity Server is more a black box as it functions as an Identity Bus) than with the Enterprise Integrator and API Manager.
Learn more about Identity Server
The Identity Server is a powerful Identity and Access Management Solution that can play a critical role in your IT landscape. If you want to know more about this product, take a look at our Identity Server trainings.
