- Make your Java web application become a JOSSO Single Sign-On partner application
- Set up Security Constraints (JEE)
- Prepare your application
- Test it
- Using the Custom User Properties Feature
- For more information
This guide will explain how to make your Java Web Application become a JOSSO Partner Application when running on a JEE Container. If you used standar JEE security APIs, you will be able to enable Single Sign-On capabilities into your Java Application by using a fully declarative approach. No need to change your application code.
The guide will be based on the provided JOSSO sample application.
- JOSSO Gateway configured and running (in any platform).
- JOSSO Agent configured in the selected platform.
- A Java Web Application, you can use the sample application distributed with JOSSO for testing purposes.
Edit the josso-agent-config.xml file installed in your platform and add a new JOSSO Partner application in the partner-apps section. The application ID must be unique within an agent.
Make sure you use your own application context when adding new partner applications, in our example we configured /partnerapp and /otherPartnerapp, this applications should be accesible at http://localhost:8080/partnerapp and http://localhost:8080/otherPartnerapp
A Web application that uses security requires the user to log in in order to access some of its resources. The user's credentials are verified against a security realm, and once authenticated, access will be granted only to specified resources within the Web application.
Security in a Web application is configured using three elements:
- The <login-config> element specifies how the user is prompted to log in and the location of the security realm. If this element is present, the user must be authenticated in order to access any resource that is constrained by a <security-constraint> defined in the Web application.
- A <security-constraint> is used to define the access privileges to a collection of resources via their URL mapping.
- A <security-role> element represents a group or principal in the realm. This security role name is used in the <security-constraint> element and can be linked to an alternative role name used in servlet code via the <security-role-ref> element.
Lets look at the complete web.xml file of your partner web application:
This web.xml file specifies that only the users associated with 'role1' can access your partner application.
When a non-authenticated user requires access to your partner application, he will be redirected to the '/partnerapp/login-redirect.jsp' page, which will redirect the user to the JOSSO Sign-on form.
Note that the role name specified in the <role-name> element must be a role that can be retrieved by the Identity Store configured in your Gateway (IdP).
In case you are running JOSSO in application server that supports EJBs, the authenticated user's identity will be propagated to the EJBs invoked by the partner web application.
JOSSO will also work with EJB 3.0 components so you can use standard JEE security annotations instead of a deployment descriptor
The security contraints should be declared in the ejb-jar.xml file of the partner EJB components. Lets look at an example of such file:
This file sets security constraints for a 'PartnerComponentEJB' Enterprise Java Bean, allowing only users associated to role 'role1' to invoke its methods.
For more information about integrating EJBs to with the Single Sign-On infrastructure you can browse the sample online from our SVN repository here http://josso.svn.sourceforge.net/viewvc/josso/branches/JOSSO_1_8_0_B/josso/examples/
Your container may require specific descriptors or configuration, take a look at the following index to see a quick setup for your platform:
- JBoss Jossify your application for JBoss - Quick Start
- Tomcat Jossify your Application for Tomcat - Quick Start
- Weblogic Jossify your application for Weblogic - Quick Start
- Jetty Jossify your application for Jetty - Quick Start
If you're not running the agent and/or gateway in your desktop box, you need to replace the 'localhost' host name by the proper host name, for example www.my-company.com
Using your web browser, contact the following url : *http://localhost:8080/partnerapp/* .
Instead of partnerapp use the web context name of your web application.
You should be redirected to the Gateway Single Sign-On logon form located in the JOSSO Gateway at *http://localhost:8080/josso/signon/login.do*.
When the sign-on form is displayed, logon using one of the user/password pairs previously inserted in the user table. Logon with the user1 user since its associated with the role1 role. This role was set in the web.xml file as authorized to access the partner web application.
On authentication the user will be redirected back to the partner application.
From the partner application it will be possible, using the standard Servlet Security API, to access the information of the logged user.
Lets see how this can be done :
You should see something like :
In this example we used as a JSP partner web application. You can protected any java web application (ie: Servlet, Struts, etc.) and roles will be available to all of them using standard java security APIs.
As seen in the previous sample configuration file, using the <userPropertiesQueryString> element its possible to make the Single Sign-On Gateway include custom user properties to the Principal. Such Principal will then be available to partner web application using the standard Servlet Security API, allowing the partner application to access additional user properties without having to query the resource containing the additional user properties.
These properties are stored in the org.josso.gateway.identity.SSOUser class instance as an array of org.josso.gateway.SSONameValuePair class instances.
To access such properties you will have to cast the User Principal associated with the HttpServletRequest in the following way :
For more detail, check the sample located in the src/webapp/samples/partnerapp/josso directory of the JOSSO distribution.
Or browse the sample online from our SVN repository here
Check the sample partner application in the JOSSO distribution located in the src/webapp/samples/partnerappdirectory. Browse it online from our SVN repository here.
Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs