Sample OIDC Java EE web app¶

By following this guide, you will be able to deploy a Java EE web application locally and secure it with OpenID Connect.

Prerequisites¶

Apache tomcat 9.x or 8.x

If you don't have it, install Apache tomcat.
A user account in the WSO2 Identity Server

If you don't already have one, create a user account in the WSO2 Identity Server.

Register the app¶

Follow the steps given below to register the sample Java EE web application in WSO2 Identity Server.

On the WSO2 Identity Server Console, go to Applications.
Click New Application and select Traditional Web Application:

Enter the following details:

Create a new web app

Name	Give a unique name to identify your application.
Protocol	Select OpenID Connect.
Authorized redirect URLs	The URL to which the user is redirected after a successful login. Use the following URL for this sample app: `http://localhost:8080/oidc-sample-app/oauth2client`

Click Create to complete the registration.
Go to the Protocol tab and take note of the Client ID and the Client secret. You will need them to configure the application later.

Tip

To provide a better experience for the user, it is recommended to configure an access URL for the application. You can set an access URL from the General tab of the application. (For this sample application, the access URL is https://localhost:8080/oidc-sample-app).

The access URL is used,

in the application catalog and discovery flows.
to redirect the user back to the application in the following scenarios.
- if the login page times out
- after a password reset
- after the self sign-up verification
to re-initiate the login flow if the login flow fails.

Download the sample¶

Click the button below to download the sample. You can also choose to view the source before doing so.

Download sample

View source

Configure the sample¶

Follow the steps given below to configure the sample app.

Move the war file that you downloaded to the {TOMCAT_HOME}/webapps folder where {TOMCAT_HOME} is the home directory of your Tomcat server.
Open a terminal, navigate to the {TOMCAT_HOME}/bin folder, and start the Tomcat server using the following command:
```
sh catalina.sh start
```
Note

This will extract the contents of the war file.
If your Tomcat server is set to auto-deploy applications, you can skip this step.
Go to the {TOMCAT_HOME}/webapps/oidc-sample-app/WEB-INF/classes folder and open the oidc-sample-app.properties file in a text editor.

Update the following in the oidc-sample-app.properties file:

consumerKey={client ID}
consumerSecret={client secret}
scope=openid,address,email,profile

callBackURL=http://localhost:8080/oidc-sample-app/oauth2client
trustedAudience=http://localhost:8080/oidc-sample-app      

issuer=https://localhost:9443/oauth2/token
authorizeEndpoint=https://localhost:9443/oauth2/authorize
logoutEndpoint=https://localhost:9443/oidc/logout
tokenEndpoint=https://localhost:9443/oauth2/token
jwksEndpoint=https://localhost:9443/oauth2/jwks
#sessionIFrameEndpoint=https://localhost:9443/oidc/checksession

skipURIs=/oidc-sample-app/index.html
indexPage=index.html
logoutURL=logout 
errorPage=error.jsp

Configuration	Description
`consumerKey`	The client id of the registered application.
`consumerSecret`	The client secret of the registered application.
`scope`	The list of OIDC scopes that are used for requesting user information. You can add OIDC scopes such as `profile` and `email` in a comma-separated list as follows: `scope=openid,address,email,profile`
`issuer`	Issuer endpoint of the WSO2 Identity Server used for id token validation: `https://localhost:9443/oauth2/token`
`authorizeEndpoint`	The authorization endpoint of the WSO2 Identity Server: `https://localhost:9443/oauth2/authorize`
`logoutEndpoint`	The logout endpoint of the WSO2 Identity Server: `https://localhost:9443/oidc/logout`
`tokenEndpoint`	The token endpoint of the WSO2 Identity Server: `https://localhost:9443/oauth2/token`
`jwksEndpoint`	The jwks endpoint of the WSO2 Identity Server: `https://localhost:9443/oauth2/jwks`

On your terminal, navigate to the {TOMCAT_HOME}/bin folder and run the following commands to restart the Tomcat server for the configurations to take effect:
```
sh catalina.sh stop
sh catalina.sh start
```

Update the java keystore¶

By default, tomcat is using the default Java keystore (cacerts) to build the SSL connection. In WSO2 Identity Server, the default certificate is a self signed certificate. This certificate needs to be added to the Java keystore. Please follow the given steps below to extract the public key from WSO2 Identity Server keystore and import it to the Java keystore.

Export the public key from WSO2 Identity Server keystore.

Command

keytool -export -alias {{ CERT_ALIAS }} -file {{ CERT_NAME }} -keystore {{ PATH_TO_KEYSTORE }} -storepass {{ KEYSTORE_PASSWORD }}

Sample
```
keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon
```
Tip

The default keystore of WSO2 Identity Server can be found in {{ IS_HOME }}/repository/resources/security directory.

Convert the certificate to X509 format.

Command

openssl x509 -in {{ CERT_NAME }} -inform der -outform pem -out {{ PEM_CERT_NAME }}

Sample

openssl x509 -in carbon_public2.crt -inform der -outform pem -out certificate.pem

Import the created .pem certificate to Java keystore.

Command

sudo keytool -import -trustcacerts -keystore {{ PATH_TO_CACERTS_KEYSTORE }} -storepass {{ CACERTS_PASSWORD }} -noprompt -alias {{ CERT_ALIAS }} -file {{ PEM_CERT_PATH }}

Sample

sudo keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit -noprompt -alias wso2carbon -file certificate.pem

After importing the certificate, restart the Tomcat server in order to fetch the latest certificates.
```
sh catalina.sh stop
sh catalina.sh start
```

Run the sample¶

Follow the steps given below to run the sample.

Access the application using the following URL: http://localhost:8080/oidc-sample-app/index.html.
Click Login. You will be redirected to the WSO2 Identity Server login page.
Enter the credentials of your user account and click Sign In.

Extend your login session

By default, the user login session is active for only 15 minutes. You can extend the session to 14 days by selecting the Remember me on this computer option provided at the login screen of your application.