Page Operations
Browse Space
Introduction
This how-to will explain how to make your Java Web Application become a JOSSO Partner Application when running on Tomcat, JBoss or Geronimo
Prerequisites
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.
Make your Java web application become a JOSSO Single Sign-On partner application
Configure the JOSSO Agent
The Catalina web container running the partner web application must know how to reach the Single Sign-On Gateway. To allow this the josso-agent-config.xml configuration file must be installed in container specific directory: $CATALINA_HOME/bin Apache Tomcat, $JBOSS_HOME/bin for JBoss and $GERONIMO_HOME/bin for Geronimo.
Lets look at the josso-agent.xml configuration file content :
 | Make sure you configure the proper Agent class for your platform |
<?xml version="1.0" encoding="ISO-8859-1" ?> <agent> <!-- Tomcat Agents --> <!--class>org.josso.tc50.agent.CatalinaSSOAgent</class--> <class>org.josso.tc55.agent.CatalinaSSOAgent</class> <!--class>org.josso.tc60.agent.CatalinaSSOAgent</class--> <!-- JBoss Agents --> <!--class>org.josso.jb32.agent.JBossCatalinaSSOAgent</class--> <!--class>org.josso.jb4.agent.JBossCatalinaSSOAgent</class--> <!--class>org.josso.jb42.agent.JBossCatalinaSSOAgent</class--> <gatewayLoginUrl>http://localhost:8080/josso/signon/login.do</gatewayLoginUrl> <gatewayLogoutUrl>http://localhost:8080/josso/signon/logout.do</gatewayLogoutUrl> <service-locator> <class>org.josso.gateway.WebserviceGatewayServiceLocator</class> <endpoint>localhost:8080</endpoint> </service-locator> <partner-apps> <partner-app> <context>/partnerapp</context> </partner-app> </partner-apps> </agent>
You should replace localhost:8080 with the hostname and port of the host where the Single Sign-On Gateway is listening. It is very important that gatewayLoginUrl and gatewayLogoutUrl use the correct host name and port, this must be the URLs the user will be accessing when attempting a login and a logout.
 | Application Context 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 |
Remember to add an entry in the $CATALINA_HOME/bin/josso-config.xml file pointing to the josso-agent-config.xml file. If gateway and agent are deployed in the same server the josso-config.xml configuration file should look like this :
<?xml version="1.0" encoding="ISO-8859-1" ?> <configuration> <xml fileName="josso-agent-config.xml"/> </configuration>
Set up Security Constraints
Web application Security Constraints
A Web application that uses security requires the user to log in in order to access its resources. The user's credentials are verified against a security realm, and once authenticated, the user will have access 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 :
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <display-name>JOSSO Partner Application</display-name> <welcome-file-list id="WelcomeFileList"> <welcome-file>index.jsp</welcome-file> </welcome-file-list> <security-constraint> <!-- Sample Security Constraint --> <web-resource-collection> <web-resource-name>protected-resources</web-resource-name> <url-pattern>/*</url-pattern> <http-method>HEAD</http-method> <http-method>GET</http-method> <http-method>POST</http-method> <http-method>PUT</http-method> <http-method>DELETE</http-method> </web-resource-collection> <auth-constraint> <role-name>role1</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login-redirect.jsp</form-login-page> <form-error-page>/login-redirect.jsp</form-error-page> </form-login-config> </login-config> <security-role > <description>The Role1</description> <role-name>role1</role-name> </security-role> </web-app>
| Application Context In this example we are assuming that the web context of your web application is 'partnerapp'. You will have to 'protect' this context with a Single Sign-On Agent as described in the Setup section of the documentation. |
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 with an entry in the 'ROLE' database table that will be retrieved by the Single Sign-On Gateway using the SQL SELECT statement specified in the josso-gateway-config.xml file.
EJB Security Constraints
In case you are running JOSSO in the JBoss application server, the authenticated user's identity will be propagated to the EJBs invoked by the partner web application.
| EJB 3.0 JOSSO will also work with EJB 3.0 components so you can use standard J2EE 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:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'> <ejb-jar> <display-name>Partner Component</display-name> <enterprise-beans> <session> <ejb-name>PartnerComponentEJB</ejb-name> <home>org.josso.samples.ejb.PartnerComponentHome</home> <remote>org.josso.samples.ejb.PartnerComponent</remote> <ejb-class>org.josso.samples.ejb.PartnerComponentEJB</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> <assembly-descriptor> <security-role> <description>Role 1</description> <role-name>role1</role-name> </security-role> <method-permission> <description>Security attributes for 'PartnerComponenttEJB' methods</description> <role-name>role1</role-name> <method> <ejb-name>PartnerComponentEJB</ejb-name> <method-name>*</method-name> </method> </method-permission> <container-transaction> <method> <ejb-name>PartnerComponentEJB</ejb-name> <method-name>*</method-name> </method> <trans-attribute>Required</trans-attribute> </container-transaction> </assembly-descriptor> </ejb-jar>
This file sets security constraints for a 'PartnerComponentEJB' Enterprise Java Bean, allowing only users associated to role 'role1' to invoke its methods.
For the user identity to be propagated to the EJB tier in JBoss, the jboss.xml file must set java:/jaas/josso as the security domain in the following way :
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 3.0//EN" "http://www.jboss.org/j2ee/dtd/jboss_3_0.dtd"> <jboss> <security-domain>java:/jaas/josso</security-domain> <enterprise-beans> <session> <ejb-name>PartnerComponentEJB</ejb-name> <jndi-name>josso/samples/PartnerComponentEJB</jndi-name> </session> </enterprise-beans> </jboss>
For more information about integrating EJBs to with the Single Sign-On infrastructure you can browse the sample online from our CVS repository here
Create the Redirect Page
When the servlet container detects that the user wishes to access a protected resource, it will redirect him to the /partnerapp/login-redirect.jsp page.
We then need to add a login-redirect.jsp JSP page to our partner web application that must look like this :
<%@page contentType="text/html; charset=iso-8859-1" language="java" session="true"%> <% response.sendRedirect(request.getContextPath() + "/josso_login/"); %>
This JSP page will redirect the user to a special URI which will inform the Single Sign-On Agent to redirect the user to the configured login form in the Single Sign-On Gateway.
To change this URL, modify the <gatewayLoginUrl> element value in the josso-agent-config.xml file.
The partner application must allow the user to logout. This action must be delegated to the Gateway by redirecting the user in the following way :
<%@page contentType="text/html; charset=iso-8859-1" language="java" session="true" %> <% response.sendRedirect(request.getContextPath() + "/josso_logout/"); %>
The Single Sign-On Agent will intercept this request an redirect the user to the configured Url in the <gatewayLogoutUrl> element of the josso-agent-config.xml file.
Build the Partner Application
Build your Partner Application as usual by including the WEB-INF/web.xml with your protected resources set as seen before.
In case of deploying a Partner Application which includes EJB components you should also include the ejb-jar.xml and jboss.xml files.
Deploy the Partner Application
In case of using Apache Tomcat, deploy your partner application WAR file in the $CATALINA_HOME/webapp directory.
In case of using JBoss, drop your partner application EAR file in the $JBOSS_HOME/server/default/deploy directory.
Testing it
Contact the Partner application
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*.
Authenticate
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.
Access 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 :
<%@ page contentType="text/html; charset=iso-8859-1" language="java" %> <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <title>Sample Partner Application - JOSSO</title> </head> <body> <p>This is a very simple JOSSO partner application</p> <p>Your username is : <b><%=request.getRemoteUser()%></b> <font color="red">(Retrieved from request.getRemoteUser())</font></p> </body> </html>
You should see something like :
This is a very simple JOSSO partner application Your username is : user1 (Retrieved from request.getRemoteUser())
|
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. |
Using the Custom User Properties Feature
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 :
... <% // Check if we have a principal ... if (request.getUserPrincipal() != null) { %> <p>Your username is : <b><%=request.getRemoteUser()%></b> <font color="red">(Retrieved from request.getRemoteUser())</font></p> <% // Cast the principal to a josso specific user, //and iterate over its properties. org.josso.gateway.identity.SSOUser ssoUser = (org.josso.gateway.identity.SSOUser) request.getUserPrincipal(); for (int i = 0 ; i < ssoUser.getProperties().length ; i++) { %> <p><%=ssoUser.getProperties()[i].getName()%> : <%=ssoUser.getProperties()[i].getValue()%> </p> <% } %> <% } ...
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
For more information
Check the sample partner application in the JOSSO distribution located in the src/webapp/samples/partnerappdirectory. Browse it online from our SVN repository here.
Comments
Care to comment on this How-To? Help keep this document relevant by passing along any constructive feedback to the josso-docs