Configuring a sample webapp with SAML SDK in WSO2 Identity Server
This guide showcases the SAML SDK in WSO2 Identity Server which allows developers to configure custom webapps with minimum hassle.
To get started, this is the structure of the web app boilerplate we would be configuring throughout this guide. The source code for the web app boilerplate can be found at: https://github.com/ChamathNS/SampleApp-boilerplate.git .
Here, we have a landing page (index.html) and another page which we want to secure (home.jsp). In the landing page, there is a button which would forward the user to the secured page. Upon clicking on the button on the landing page, we want to authenitcate the user before granting access to the secured page.
This guide outlines the steps needed to use the SAML SDK which is readily available with WSO2 Identity Server, and configure the webapp to use the SDK for the purpose of securing the home.jsp page.
For clarity, the rest of the guide is structured into three sections.
- Configuring the web app
- Configuring the WSO2 Identity Server
- Retrieving user attributes in the web app
Configuring the Web App
First, let’s look at the components of the sample webapp which we will be using throughout this guide. To give an overview, the final project structure for the sampleApp would look similar to this.
In this section, we would go through each file of the web app and look into what configurations need to be made for it to utilize the SAML SDK.
Starting with the pom.xml, the following dependencies should be added for the webApp to be using the SAML SDK.
Next, the webapp itself has two pages, index.html and home.jsp, and a web.xml file.
The index.html contains a login button which we would use to forward the user to the secured page.
<form method="post" action="home.jsp">Now we need to update the form action to trigger a SAML authentication request as follows,
<form method="post" action="samlsso?SAML2.HTTPBinding=HTTP-POST">The home.jsp page is a page which we want to secure i.e. in case there are no active sessions, the http://localhost:8080/SampleApp/home.jsp should not be accessible. In the sampleApp we are using, if there is no active session in place, we would redirect the user for authentication. In the home.jsp, there is a logout link which will be used to create a SLO request.
<a href="logout?SAML2.HTTPBinding=HTTP-POST">Logout</a>Before the web.xml configurations, we will look at adding the resources files.
In the sampleApp, create a file named sampleApp.properties in the resources directory. The sampleApp.properties file contains properties similar to the following.
These properties are required for the SAML SDK to communicate with the WSO2 Identity Server. Next, copy a keystore file to the resources directory. In our example,
properties file: “sampleApp.properties”
keystore file: “wso2carbon.jks”
You may need to update the properties file entries to reflect the properties of your keystore. For simplicity, we are using the wso2carbon.jks keystore file of the WSO2 Identity Server which resides in “<IS_HOME>/repository/resources/security/” directory.
Finally, copy and paste the following web.xml configurations to the WEB-INF/web.xml file. Make sure that you update param-values of the context-params,
<param-name>property-file</param-name>
<param-name>certificate-file</param-name>to match yours.
Configuring the WSO2 Identity Server
This section of the guide will explain how to create a service provider in WSO2 Identity Server which would be utilized to handle the web app requests.
To register the SampleApp as a service provider,
- Sign in to the Management Console.
- On the Main menu, click Identity > Service Providers > Add.
- Fill in the Service Provider Name and provide a brief Description (optional) of the service provider as follows.
- Click Register to add the new service provider.
- Next, enter a suitable name for the service provider in the Service Provider Name text box.
- Next, under the Inbound Authentication Configuration section, click SAML2 Web SSO Configuration and click on configure.
- Select Manual Configuration and enter the required details as given below.
Issuer — SampleApp (This needs to be identical to the SAML2.SPEntityId property in the SampleApp.properties file)
Assertion Consumer URL — http://localhost:8080/SampleApp/home.jsp (This needs to be identical to the SAML2.AssertionConsumerURL property in the SampleApp.properties file)
NameID format — urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Please refer to Configuring SAML2 Web SSO when filling out the other fields.
- Finally, click on “register” to save the service provider configuration.
Retrieving user attributes in the web app
In the final section of the guide, we would focus on retrieving user attributes from the Identity Server into the SampleApp.
First, the service provider claim configuration needs to be updated.
To update it,
- From the Management Console, click on Identity > Service Providers > List.
- There, click on the “edit” icon for the SampleApp Service Provider that was registered in the above steps.
- Next, expand the Claim Configuration section.
- From the expanded menu, set the Claim Mapping Dialect to Use Local Claim Dialect and click on Add Claim URI that is against the Requested Claims field.
- Add the claims you need to retrive from the web app as following. (eg: country, lastname)
- Then, set the Subject Claim URI to a claim you want as the subject. In the example, we are using http://wso2.com/claims/fullname.
- After that, click on update to save the configurations of the service provider.
Next, the web app needs to be configured to read the attributes sent from the Identity Server upon successful authentication. In the SampleApp, we would customize the home.jsp file as follows to retrieve the user attributes.
In L33,
Map<String, String> saml2SSOAttributes = sessionBean.getSAML2SSO().getSubjectAttributes();
retrives the subject attributes into a Map. Then, in the example, from L51-L64, the retrived attributes are displayed in a table in the home.jsp. The final home.jsp would look similar to this.
The source code for the SampleApp is hosted at https://github.com/ChamathNS/SampleApp.git
