Asgardeo 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 Asgardeo Tomcat SAML Agent
- Building from the source
- Contributing
- License
You can experience the capabilities of Asgardeo Tomcat SAML Agent by following this small guide which contains main sections listed below.
-
Open a terminal window inside a preferred directory on your machine.
-
Deploy the sample app.
- a. Execute the following command to start the sample Docker container.
docker container run --rm --name tomcat-saml-agent-sample -itdp 8080:8080 asgardeo/tomcat-saml-agent-sample- b. You can also manually deploy the sample app in a Tomcat server without using the docker image. Simply download
sample-app.warfrom here and deploy.
-
Add the following entry to the
/etc/hostsfile of your machine to configure the hostname.127.0.0.1 localhost.com
Here we are using Asgardeo as the SAML Identity Provider.
-
Navigate to Asgardeo Console and click on Applications under Develop tab.
-
Click on New Application and then Traditional Web Application.
-
Select SAML from the selection and enter any name as the name of the app and add the Assertion Consumer Service URL and Issuer.
-
Click on Register. You will be navigated to management page of the created application.
Try out the application by accessing the URL http://localhost.com:8080/sample-app/index.html in your web browser.
This section explains detailed walkthrough on how key aspects handled in the Asgardeo Tomcat SAML Agent.
- Classify secure resources, unsecured resources
- Trigger authentication
- Retrieve user attributes
- Trigger logout
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.
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.
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();
%>
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.
Asgardeo 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 integrate the Tomcat SAML Agent into your pre-built webapps, follow the guide here.
To integrate the Tomcat SAML Agent into your java source project, follow the guide here.
Please read Contributing to the Code Base for details on our code of conduct, and the process for submitting pull requests to us.
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.
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent