Integrate your Java EE webapp with SAML

Follow the steps given below to authenticate users to your Java EE web application deployed on Tomcat using the Asgardeo Tomcat SAML Agent (opens new window) which enables SAML-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 already registered in Asgardeo. If you don't, see the instructions on registering a SAML application.

Install the SDK

Follow the steps given below to install the SAML agent.

1. Add the relevant dependencies.

   To get started, you need to enable the SAML agent in your application's project by adding the relevant dependencies to the pom.xml file.

   <dependency>
       <groupId>io.asgardeo.tomcat.saml.agent</groupId>
       <artifactId>io.asgardeo.tomcat.saml.agent</artifactId>
       <version>0.1.31</version>
   </dependency>
   

2. Add the nexus repository.

   The agent is hosted at WSO2 Internal Repository. Point to this nexus repository to resolve the dependency mentioned above.

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

See the reference documentation (opens new window) to learn more.

Initialize the SDK

Follow the steps given below to initialize the SAML agent.

Create the configuration file

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

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

SAML2.AssertionConsumerURL=<acs_url>
SAML2.SPEntityId=<entity_id>

#Asgardeo related configs
SAML2.IdPEntityId=accounts.asgardeo.io/t/<organization_name>
SAML2.IdPURL=https://api.asgardeo.io/t/<orgaization_name>/samlsso 
IdPPublicCert=<public_cert_of_asgardeo_organization>
IdPPublicCertAlias=wso2carbon

#Config properties
EnableSAML2SSOLogin=true
SAML2.EnableSLO=true
SAML2.EnableResponseSigning=false
SAML2.EnableAssertionSigning=false
SAML2.EnableAssertionEncryption=false
SAML2.EnableRequestSigning=false
SAML2.IsPassiveAuthn=false      

SAML2.SLOURL=logout
SkipURIs=<YOUR_APP_PATH>/index.html
IndexPage=index.html
ErrorPage=/error.jsp
SAML2SSOURL=samlsso

# App keystore related configs
KeyStorePassword=<app_keystore_password>
PrivateKeyAlias=<app_private_key_alias>
PrivateKeyPassword=<app_private_key_password>

For advanced use cases such as SAML response signing, the Asgardeo SAML Agent uses a keystore with your private key. If your application doesn't have a keystore already, generate a keystore file and copy it to the <APP_HOME>/src/main/resources directory. Make sure to update KeyStorePassword, PrivateKeyAlias, and PrivateKeyPassword with relevant values.

Find the configuration information below:

Configuration	Description
SAML2.AssertionConsumerURL	Specifies the URL to redirect to after login and logout. See See ACS URLs
SAML2.SPEntityId	This is the unique name of the application used when registering your application with Asgardeo. See how to register a SAML app manually via the Asgardeo Console.
SAML2.IdPEntityId	This is the issuer of Asgardeo. This is always accounts.asgardeo.io/t/{organization_name}/oauth2/token.
SAML2.IdPURL	This specifies the endpoint of Asgardeo to which login and logout requests should be sent. Note that the organization name should be replaced in the URL with the correct value. 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.
EnableSAML2SSOLogin	Specifies whether 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. If this configuration is set to true, then 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. If this configuration is set to true, then 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. If this configuration is set to true, then enable encryption for SAML assertion from Asgardeo.
SAML2.EnableRequestSigning	If this configuration is set to true, Asgardeo validates the SAML authentication request and logout request. If this configuration is set to true, then enable request signing from Asgardeo.
SAML2.IsPassiveAuthn	Specifies whether to enable passive authentication
skipURIs	Defines the web pages in your application that should not be secured and does not require authentication
KeyStorePassword	Keystore password of your application
PrivateKeyAlias	Private key alias of your application
PrivateKeyPassword	Password of the private key of your application

See the complete list of configuration properties (opens new window).

Configure the keystore

Copy the following configurations to the <APP_HOME>/WEB-INF/web.xml file and change the certificate-file parameter to the name of your keystore file.

<filter>
    <filter-name>SAML2SSOAgentFilter</filter-name>
    <filter-class>io.asgardeo.tomcat.saml.agent.SAML2SSOAgentFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>SAML2SSOAgentFilter</filter-name>
    <url-pattern>*.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>SAML2SSOAgentFilter</filter-name>
    <url-pattern>*.html</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>SAML2SSOAgentFilter</filter-name>
    <url-pattern>/samlsso</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>SAML2SSOAgentFilter</filter-name>
    <url-pattern>/logout</url-pattern>
</filter-mapping>

<listener>
    <listener-class>io.asgardeo.tomcat.saml.agent.SSOAgentContextEventListener</listener-class>
</listener>
<context-param>
    <param-name>property-file</param-name>
    <param-value>sample-app.properties</param-value>
</context-param>
<context-param>
    <param-name>certificate-file</param-name>
    <param-value>KEYSTORE_FILE_NAME</param-value>
</context-param>

Add login

In the index.html file, add a login button to be used to redirect users to secure pages.

When the user clicks the button, the SAML agent intercepts the request and initiates the SAML login flow if an authenticated session does not already exist.

<form action="<HOME_PAGE>" method="post">
    <input type="submit" value="log in">
</form>

Add logout

In the previous steps, you implemented login for your app. Now you need a way to log users out of your application and remove the user sessions from Asgardeo.

When the user initiates the logout, the local authenticated application session is cleared and the session in Asgardeo is terminated.

Add the following snippet to enable logout.

<form action="logout?SAML2.HTTPBinding=HTTP-POST" method="get">
    <input type="submit" value="Log Out">
</form>

See the Asgardeo Tomcat SAML Agent documentation (opens new window) for more information.