Integrate your Java EE webapp with OIDC

# Integrate your Java EE webapp with OIDC

Follow the steps given below to authenticate users to your Java EE web application deployed on Tomcat using the Asgardeo Tomcat OIDC Agent (opens new window) which enables OIDC-based login and logout.

# Prerequisites

Download (opens new window) Apache Tomcat 9.x or 8.x in your local environment.
Download (opens new window), and install (opens new window) Apache Maven (3.6.x or higher) as the package manager if you already haven't.
You need to have an application registered in Asgardeo. 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>

1
2
3
4
5

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>

1
2
3
4
5
6
7
8
9
10
11
12

# Initialize the SDK

To initialize the OIDC agent, you need a property file with the configurations such as the Asgardeo endpoints. The Asgardeo OIDC agent reads the configurations from this file.

Create a file named oidc-sample-app.properties in the <YOUR_APP>/src/main/resources directory, using the content below.

Info

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://api.asgardeo.io/t/<organization_name>/oauth2/authorize
logoutEndpoint=https://api.asgardeo.io/t/<organization_name>/oidc/logout
tokenEndpoint=https://api.asgardeo.io/t/<organization_name>/oauth2/token
issuer=https://api.asgardeo.io/t/<organization_name>/oauth2/token
jwksEndpoint=https://api.asgardeo.io/t/<organization_name>/oauth2/jwks
skipURIs=<YOUR_APP_PATH>/index.html

1
2
3
4
5
6
7
8
9
10
11

A comprehensive list of the properties used above can be found in the Configuration Catalog (opens new window) .

Finally, copy and paste the following configuration to the <YOUR_APP>/src/main/webapp/WEB-INF/web.xml file.

<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>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

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>

1
2
3

# 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 Asgardeo is terminated.

<form action="logout" method="get">
    <input type="submit" value="Log Out">
</form>