Java EE sample web app with SAML

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

Prerequisites

• Apache tomcat 9.x or 8.x

  If you don't have it, install Apache tomcat (opens new window).

• A user account in Asgardeo

  If you don't already have one, create a user account in Asgardeo.

Register the app

Follow these steps given below to register the sample Java EE web application in Asgardeo.

1. On the Asgardeo Console (opens new window), go to Applications.

2. Click New Application and select Traditional Web Application.

   

3. Enter the following details:

   

   Name	Give a unique name to identify your application. sample-app
   Protocol	Select SAML.

4. Select Manual as the configuration type and enter the following details:

   Learn more about other SAML configuration types.

   Issuer	Add a unique identifier for the application. This should be used in the SAML authentication request sent from the client. You can't change the issuer after the app is registered. sample-issuer
   Assertion consumer service URLs	The URL to which the user is redirected after login and logout. Use the following URL for this sample app: http://localhost:8080/sample-app/home.jsp

5. Click Register to complete the registration.

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 for the application from the General tab. (For this sample application, the access URL is https://localhost:8080/sample-app)

Why do we recommend this?

• It will be used in the application catalog and discovery flows.
• We will use it to redirect the user back to the application in the following scenarios.
  • If the login page times out
  • After a password reset
  • After self sign-up verification
• If the login flow is failed, we will provide an option for the user to re-initiate the login flow using this URL.

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.

1. Move the war file that you downloaded to the <TOMCAT_HOME>/webapps folder where <TOMCAT_HOME> is the root of your Tomcat server.

2. Open a terminal, navigate to the <TOMCAT_HOME>/bin folder, and start the Tomcat server using the following command:

   This will extract the contents of the war file.
   If your Tomcat server is set to auto-deploy applications, you can skip this step.

   sh catalina.sh start
   

3. Go to the <TOMCAT_HOME>/webapps/sample-app/WEB-INF/classes folder and open the sample-app.properties file in a text editor.

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

   Important

   • Update the SAML2.IdPEntityId parameter with the Asgardeo issuer, which is api.asgardeo.io/t/{organization_name}.
   • Replace {organization_name} with the name of your organization.
   • SAML2.SPEntityId should match the issuer name entered when registering the application in Asgardeo.

   SAML2.AssertionConsumerURL=http://localhost:8080/sample-app/home.jsp
   SAML2.SPEntityId=sample-issuer
   SAML2.IdPEntityId=api.asgardeo.io/t/{organization_name}
   SAML2.IdPURL=https://api.asgardeo.io/t/{orgaization_name}/samlsso 
   IdPPublicCert={public_cert_of_asgardeo_organization}
   SkipURIs=/sample-app/index.html
   
   #Other properties
   IdPPublicCertAlias=wso2carbon
   EnableSAML2SSOLogin=true
   SAML2.EnableSLO=true
   SAML2.EnableResponseSigning=false
   SAML2.EnableAssertionSigning=false
   SAML2.EnableAssertionEncryption=false
   SAML2.EnableRequestSigning=false
   SAML2.IsPassiveAuthn=false      
   SAML2.SLOURL=logout
   IndexPage=index.html
   ErrorPage=/error.jsp
   SAML2SSOURL=samlsso
   

   Configuration	Description
   SAML2.AssertionConsumerURL	The URL to which the user is redirected after login and logout.
   SAML2.SPEntityId	The SAML issuer that is used when registering your application with Asgardeo.
   SAML2.IdPEntityId	The issuer name of Asgardeo. api.asgardeo.io/t/{organization_name}
   SAML2.IdPURL	The endpoint of Asgardeo to which login and logout requests should be sent: https://api.asgardeo.io/t/{organization_name}/samlsso
   IdPPublicCert	This specifies the public certificate of Asgardeo. You can obtain the public certificate from the Asgardeo Console. See how to get SAML configurations from the Asgardeo Console.
   skipURIs	Defines the web pages in your application that should not be secured and does not require authentication.

   Other properties

   Configuration	Description
   EnableSAML2SSOLogin	Specifies whether single sign-on is enabled for this application.
   SAML2.EnableSLO	Specifies whether logout is enabled for this application.
   SAML2.EnableResponseSigning	If this configuration is set to true, the application validates the signature in the SAML response. You also need to enable response signing from Asgardeo. If this configuration is set to false, the application does not mandate response signing from Asgardeo.
   SAML2.EnableAssertionSigning	If this configuration is set to true, the application validates the signature in the SAML assertion. You also need to enable response signing from Asgardeo. If this configuration is set to false, the application does not mandate response signing from Asgardeo.
   SAML2.EnableAssertionEncryption	If this configuration is set to true, the application expects an encrypted SAML assertion. You also need to enable encryption for SAML assertions from Asgardeo.
   SAML2.EnableRequestSigning	If this configuration is set to true, Asgardeo validates the SAML authentication request and logout request. You also need to enable request signing from Asgardeo.
   SAML2.IsPassiveAuthn	Specifies whether to enable passive authentication.
   KeyStorePassword	Keystore password of your application.
   PrivateKeyAlias	Private key alias of your application.
   PrivateKeyPassword	Password of the private key of your application.

5. In the <TOMCAT_HOME>/bin> folder, run the following commands to restart the Tomcat server for the configurations to take effect:

   sh catalina.sh stop
   sh catalina.sh start
   

Run the sample

Follow the steps given below to run the sample.

1. Access the application using the following URL: http://localhost:8080/sample-app/index.html.

   

2. Click Login. You will be redirected to the Asgardeo login page.

   

3. Enter 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.