Securing Java EE Web Apps with Asgardeo Java OIDC SDK
How to Use Asgardeo Java OIDC SDK to Secure Java EE Web Apps
The Asgardeo Java OIDC SDK along with the Asgardeo Tomcat OIDC Agent enables you to add OIDC-based login, log out to your Java EE web apps with minimum hassle. In this guide, we will focus on how to integrate the Asgardeo OIDC Agent which has the Asgardeo Java OIDC SDK under the hood, to your existing Java EE web app.
In case you want to try out the functionalities of the SDK before integrating it to your own app, a sample app demonstrating the OIDC based authentication/authorization, logout and attribute retrieval is hosted at https://github.com/asgardeo/asgardio-tomcat-oidc-agent.
You can download the pre-built oidc-sample-app.war from here (For the latest released version, please visit the releases page) and try it out. You can read more on how to try out the sample from our guide on running the sample apps.
WSO2 has released an early adopter version of Asgardeo, an IDaaS that sets new industry standards for enabling developers without security expertise to easily embed CIAM features into their apps within minutes. Try out Asgardeo’s free trial or discover more about its features here or why not join the IAM4DEVS community to get the latest tips and tricks on all things Identity! Alternatively, if you’re looking for an enterprise grade, API driven, open source solution that can manage millions of user identities without spiralling costs please view WSO2 Identity Server.
In this guide, we would be using Asgardeo; the latest IDaaS offering by WSO2, as our Authorization Server.
Prerequisites
2. An application registered in Asgardeo. You can follow the instructions on registering an OIDC application to register one.
3. A customer user account in Asgardeo. Follow the creating a customer account guide to creating one.
Configuring the web app
The Java EE web app we would be configuring would have the following structure.
First, download the lib.zip included in the releases.
Extract the downloaded lib.zip file to the <APP_HOME>/WEB-INF directory. (If you already have a lib folder in your web app, merge the content of the downloaded lib.zip file into the existing lib folder.)
Next, we will look at adding the resources files. In the my-app-1.0, create a file named my-app.properties in the <APP_HOME>/WEB-INF/classes directory. The my-app.properties file contains properties similar to the following:
Update the consumerKey, ConsumerSecret and organization_name properties according to your application configurations in Asgardeo.
These properties are required for the OIDC SDK which is running underneath the OIDC tomcat agent to communicate with the Authorization Server. A comprehensive list of the properties can be found in the Configuration Catalog.
To finish off the web app configurations, copy and paste the following configurations to the <APP_HOME>/WEB-INF/web.xml file.
Enable login
For the sake of simplicity, let's say that my-app-1.0 has two pages; a landing page that should be publicly accessible and a secured page that should be granted access upon successful authentication. The index.html contains a login button that would forward the user to the secured home.jsp page. Follow the Configuration Catalog to get more info on how to define a landing page like in this example for your webapp.
<form action=”home.jsp” method=”post”>
<input type=”submit” value=”log in”>
</form>The home.jsp is the page which we want to secure i.e. in case there are no active sessions, the http://localhost:8080/my-app-1.0/home.jsp should not be accessible. In the web app we have, if there is no active session in place, we would redirect the user for authentication.
Note that in the Asgardeo Tomcat Agent, you can define what pages should not be secured by using the skipURIs property. And all the other pages in your web app will be treated as secured pages.
Enable logout
From a secured page, we can use the following snippet to add a logout flow. This would clear the authenticated session of the user from the Authorization Server and redirect the user back to the application landing page.
<form action="logout" method="get">
<input type="submit" value="Log Out">
</form>Note: The action=”logout” has to match the value for the logoutURL property in the my-app.properties file.
Retrieving user attributes
The web app needs to be configured to read the attributes sent from the Identity Server upon successful authentication. In the my-app-1.0, we would customize the home.jsp file as follows to retrieve the user attributes.
First, we would need the following imports to be added to the home.jsp file.
<%@ page import="io.asgardeo.java.oidc.sdk.SSOAgentConstants" %>
<%@ page import="io.asgardeo.java.oidc.sdk.bean.SessionContext" %>
<%@ page import="io.asgardeo.java.oidc.sdk.bean.User" %>
<%@ page import="java.util.Map" %>Next, by adding the following snippets, we would be able to retrieve the user claims as provided by the Identity Provider.
<%
// Retrieve the current session.
final HttpSession currentSession = request.getSession(false); // Logged in session context.
final SessionContext sessionContext = (SessionContext)
currentSession.getAttribute(SSOAgentConstants.SESSION_CONTEXT); // Logged in user.
final User user = sessionContext.getUser(); // Attributes of the logged in user.
Map<String, Object> customClaimValueMap = user.getAttributes();
%>
Then, we can use the customClaimValueMap in the <APP_HOME>/home.jsp to use the retrieved user attributes in our application business logic.
Configuring the Asgardeo OIDC application
Log in to your Asgardeo account and navigate to Develop -> Applications page. There, you can find all the applications you have registered for your Asgardeo organization.
Click on the edit button to configure the application you created for your Java EE web app.
In the Protocol tab, you can find the client ID and the Client Secret for your registered application. Copy the Client ID and update the consumerKey property in your my-app.properties file we previously created. Next, copy the Client Secret and update the consumerSecret property in the my-app.properties file.
Scroll down the protocols page and update the Authorized redirect URLs section with the callback URL for your application. This value should be the same value we configured in the callbackURL property in the my-app.properties file.
Finally, click on Update at the bottom of the page. Now we are done with the application configuration part.
Trying Out
First, restart the web server in which you have hosted your Java EE web app to make the web.xml changes applicable.
Now go to the web app landing page and click on log in.
Then, you will be redirected to the Asgardeo login page where the customer user you created would be providing their credentials. Upon successful authentication, the user would be redirected to the application home page as follows.
Great!
Now you have secured your Java EE web app with the Asgardeo OIDC SDK. You can explore how you can tighten the security and improve the user experience for the login flows by referring to the Asgardeo Authentication guides.
Share your experience with using the SDKs in the IAM4DEVS Community :)
Thanks for reading!
