Integrate SAML with your Java EE webapp

Follow the steps given below to authenticate users to your Java EE web application deployed on Tomcat using the Tomcat SAML Agent which enables SAML-based login and logout.

Try out the sample app

Prerequisites

• Download Apache Tomcat 9.x or 8.x in your local environment.
• Download and install 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 the WSO2 Identity Server. 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 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 the WSO2 Identity Server endpoints. The WSO2 Identity Server SAML agent reads the configurations from this file.

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

```saml
SAML2.AssertionConsumerURL={acs_url}
SAML2.SPEntityId={entity_id}
SAML2.IdPEntityId=localhost
SAML2.IdPURL=https://localhost:9443/samlsso
SAML2SSOURL=samlsso
EnableSAML2SSOLogin=true
SAML2.EnableSLO=true
SAML2.SLOURL=logout
SkipURIs=/sample-app/index.html
IndexPage=index.html
ErrorPage=/error.jsp
SAML2.EnableResponseSigning=false
SAML2.EnableAssertionSigning=false
SAML2.EnableAssertionEncryption=false
SAML2.EnableRequestSigning=true
SAML2.IsPassiveAuthn=false
IdPPublicCert={public_cert_of_identity-server}
KeyStorePassword=wso2carbon
PrivateKeyAlias=wso2carbon
IdPPublicCertAlias=wso2carbon
PrivateKeyPassword=wso2carbon
```

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 the WSO2 Identity Server.
SAML2.IdPEntityId	The issuer name of the WSO2 Identity Server. localhost
SAML2.IdPURL	The endpoint of the WSO2 Identity Server to which login and logout requests should be sent: https://localhost:9443/samlsso
IdPPublicCert	This specifies the public certificate of the WSO2 Identity Server. You can obtain the public certificate from the Console. See how to get SAML configurations from the WSO2 Identity Server Console.
skipURIs	Defines the web pages in your application that should not be secured and does not require authentication.
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 SAML response. You also need to enable response signing from WSO2 Identity Server. If this configuration is set to false, the application does not mandate response signing from WSO2 Identity Server.
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 WSO2 Identity Server. If this configuration is set to false, the application does not mandate response signing from WSO2 Identity Server.
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 WSO2 Identity Server.
SAML2.EnableRequestSigning	If this configuration is set to true, WSO2 Identity Server validates the SAML authentication requeand logout request. You also need to enable request signing from WSO2 Identity Server.
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.

See the complete list of configuration properties.

Configure the keystore

Copy the following configurations to the /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 WSO2 Identity Server.

When the user initiates the logout, the local authenticated application session is cleared and the session in WSO2 Identity Server 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 Tomcat SAML Agent documentation for more information.