Integrate OIDC with your Java EE webapp¶
Follow the steps given below to authenticate users to your Java EE web application deployed on Tomcat using the Tomcat OIDC Agent which enables OIDC-based login and logout.
Prerequisites¶
- Download Apache Tomcat 9.x or 8.x in your local environment.
- Download, and install Apache Maven (3.6.x or higher) as the package manager if you already haven't.
- You need to have an application registered in the WSO2 Identity Server. If you don't, see the instructions on registering an OIDC application.
Install the SDK¶
To get started with the OIDC agent, you need to add relevant dependencies. By updating the pom.xml
file with the following dependency, you can add the OIDC agent to your project.
<dependency>
<groupId>io.asgardeo.tomcat.oidc.agent</groupId>
<artifactId>io.asgardeo.tomcat.oidc.agent</artifactId>
<version>0.1.27</version>
</dependency>
The Agent is hosted at WSO2 Internal Repository. To resolve the dependency mentioned above, point to the repository as follows.
<repositories>
<repository>
<id>wso2.releases</id>
<name>WSO2 internal Repository</name>
<url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
<releases>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>ignore</checksumPolicy>
</releases>
</repository>
</repositories>
Initialize the SDK¶
To initialize the OIDC agent, you need a property file with the configurations such as the WSO2 Identity Server endpoints. The OIDC agent reads the configurations from this file.
Create a file named oidc-sample-app.properties
in the
Note
The skipURIs
property defines the web pages in your application that should not be secured, and do not require authentication.
Few of the configurations such as callBackURL
and skipURIs
depends on the context path of your application.
consumerKey=<consumerKey>
consumerSecret=<consumerSecret>
callBackURL=<YOUR_APP_PATH>/oauth2client
scope=openid
logoutURL=logout
authorizeEndpoint=https://localhst:9443/localhost:9443/oauth2/authorize
logoutEndpoint=https://localhst:9443/oidc/logout
tokenEndpoint=https://localhst:9443/oauth2/token
issuer=https://localhst:9443//oauth2/token
jwksEndpoint=https://localhst:9443/oauth2/jwks
skipURIs=<YOUR_APP_PATH>/index.html
A comprehensive list of the properties used above can be found in the Configuration Catalog .
Finally, copy and paste the following configuration to the
<filter>
<filter-name>OIDCAgentFilter</filter-name>
<filter-class>io.asgardeo.tomcat.oidc.agent.OIDCAgentFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>OIDCAgentFilter</filter-name>
<url-pattern>/logout</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>OIDCAgentFilter</filter-name>
<url-pattern>/oauth2client</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>OIDCAgentFilter</filter-name>
<url-pattern>*.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>OIDCAgentFilter</filter-name>
<url-pattern>*.html</url-pattern>
</filter-mapping>
<listener>
<listener-class>io.asgardeo.tomcat.oidc.agent.SSOAgentContextEventListener</listener-class>
</listener>
<context-param>
<param-name>app-property-file</param-name>
<param-value>oidc-sample-app.properties</param-value>
</context-param>
<listener>
<listener-class>io.asgardeo.tomcat.oidc.agent.JKSLoader</listener-class>
</listener>
Add login¶
In the index.html
file, add a login button to redirect the user to secure pages upon successful login.
Once the user clicks on the button, the request will be intercepted by the OIDC agent and will initiate the OIDC Login flow if it does not find an authenticated application session.
<form action="<HOME_PAGE>" method="post">
<input type="submit" value="Log In">
</form>
Add logout¶
Add the following snippet to enable logout.
When the user initiates the logout, the local authenticated application session is cleared and the session in the WSO2 Identity Server is terminated.
<form action="logout" method="get">
<input type="submit" value="Log Out">
</form>
See the Tomcat OIDC Agent documentation for more information on how it works.