Sample SAML Java EE web app¶
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.
-
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.
-
On the Asgardeo Console, go to Applications.
-
Click New Application and select Traditional Web Application.
-
Enter the following details:
Name Give a unique name to identify your application. e.g.:
sample-app
Protocol Select SAML. Configruation type Select Manual (Learn more about 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. e.g.:
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
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/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.
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 root of your Tomcat server. -
Open a terminal, navigate to the
{TOMCAT_HOME}/bin
folder, and start the Tomcat server using the following command: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.
sh catalina.sh start
-
Go to the
{TOMCAT_HOME}/webapps/sample-app/WEB-INF/classes
folder and open thesample-app.properties
file in a text editor. -
Update the following in the
sample-app.properties
file:Note
- Update the SAML2.IdPEntityId parameter with the Asgardeo issuer, which is
api.asgardeo.io/t/{organization_name}
. - 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 tofalse
, 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 tofalse
, 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. - Update the SAML2.IdPEntityId parameter with the Asgardeo issuer, which is
-
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.
-
Access the application using the following URL:
http://localhost:8080/sample-app/index.html
. -
Click Login. You will be redirected to the Asgardeo login page.
-
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 to14 days
by selecting the Remember me on this computer option provided at the login screen of your application.