Asgardio Tomcat SAML Agent

Asgardio Tomcat SAML Agent enables you to add SAML based login, logout to your Apache Tomcat web apps in simple manner.

• Getting Started
• How it works
• Integrating Asgardio Tomcat SAML Agent
  • To your existing webapp
  • To your Java source project
• Building from the source
• Contributing
  • Reporting issues
• License

Getting started

You can experience the capabilities of Asgardio Tomcat SAML Agent by following this small guide which contains main sections listed below.

• Prerequisites
• Configuring the sample
• Configuring Identity Server
• Running the sample

Prerequisites

1. Docker

Configuring the sample

1. Open a terminal window inside a preferred directory on your machine.
2. Execute the following command to start the sample Docker container.

   $ docker container run --rm --name tomcat-saml-agent-sample -itdp 8080:8080 asgardio/tomcat-saml-agent-sample
   

3. Add the following entry to the /etc/hosts file of your machine to configure the hostname.

   127.0.0.1 localhost.com
   

Configuring Identity Server

Here we are using WSO2 Identity Server as the SAML Identity Provider. The sample can be configured with any other preferred Identity Provider as well.

1. Open a terminal window inside a preferred directory on your machine.
2. Execute the following command to start the WSO2 IS Docker container.

   $ docker container run --rm -itdp 9443:9443 --link tomcat-saml-agent-sample wso2/wso2is
   

3. Execute the following command to download the shell script to create a Service Provider in WSO2 IS.

   $ curl -o create_service_provider.sh https://raw.githubusercontent.com/asgardio/asgardio-tomcat-saml-agent/master/create_service_provider.sh
   

4. Execute the following command to assign executable permission to the create_service_provider.sh script.

   $ chmod +x create_service_provider.sh
   

5. Execute the following command to create a SAML Service Provider in WSO2 IS.

   $ sh create_service_provider.sh
   

Running the sample

Try out the application by accessing the URL http://localhost.com:8080/sample-app/index.html in your web browser.

How it works

This section explains detailed walkthrough on how key aspects handled in the Asgardio Tomcat SAML Agent.

• Classify secure resources, unsecured resources
• Trigger authentication
• Retrieve user attributes
• Trigger logout

Classify secure resources, unsecured resources

In the sample-app, we have two pages. A landing page (index.html) which we have not secured, and another page (home.jsp) which we have secured.

IndexPage property of the sample-app.properties file in the <APP_HOME>/WEB-INF/classes directory is used to define the landing page of the webapp which is also considered as an unsecured page. Also the same page is used as the page that the user get redirected once the logout is done. Here we have set <APP_HOME>/index.html as the value of IndexPage property. IndexPage=/sample-app/index.html

By default, all the other pages are considered as secured pages. Hence home.jsp will be secured without any other configurations.

Trigger authentication

In the <APP_HOME>/index.html page, we have added the action for the login button to trigger a SAML authentication:

<form action="samlsso?SAML2.HTTPBinding=HTTP-POST" method="post">
    <div class="element-padding">
        <input style="height: 30px; width: 60px" type="submit" value="log in">
    </div>
</form>

The button click would trigger an authentication request, and redirect the user to the IdP authentication page. Upon successful authentication, the user would be redirected to the <APP_HOME>/home.jsp page.

Retrieve user attributes

In the <APP_HOME>/home.jsp file, we have added the following to get the user subject value and the user attributes referring the SDK API.

<%
    // Retrieve the session bean.
    LoggedInSessionBean sessionBean = (LoggedInSessionBean) session.getAttribute(SSOAgentConstants.SESSION_BEAN_NAME);

    // SAML response
    SAML2SSO samlResponse = sessionBean.getSAML2SSO();

    // Autheticated username
    String subjectId = samlResponse.getSubjectId();

    // Authenticated user's attributes
    Map<String, String> saml2SSOAttributes = samlResponse.getSubjectAttributes();
%>

Trigger logout

In the <APP_HOME>/home.jsp file, we have added the following to trigger a SLO flow:

<a href="logout?SAML2.HTTPBinding=HTTP-POST">Logout</a>

Clicking on the logout link would trigger the SLO flow engaging the same filter mentioned above. The user would be redirected to the page configured via the IndexPage property previously discussed.

Integrating Asgardio Tomcat SAML Agent

Asgardio Tomcat SAML Agent can be integrated in to your applications in two different ways.

It can be integrated to your java source project of the webapp when the web application is in development stage.

And, the Tomcat SAML agent can be integrated into a pre-built webapp as well.

To your existing webapp

To integrate the Tomcat SAML Agent into your pre-built webapps, follow the guide here.

To your Java source project

To integrate the Tomcat SAML Agent into your java source project, follow the guide here.

Contributing

Please read Contributing to the Code Base for details on our code of conduct, and the process for submitting pull requests to us.

Reporting issues

We encourage you to report issues, improvements, and feature requests creating git Issues.

Important: And please be advised that security issues must be reported to [email protected], not as GitHub issues, in order to reach the proper audience. We strongly advise following the WSO2 Security Vulnerability Reporting Guidelines when reporting the security issues.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.