Introduction

This how-to will explain how to make your Java Web Application become a JOSSO Partner Application when running on Weblogic

Prerequisites

JOSSO Gateway configured and running (in any platform).
JOSSO Agent configured and running in Weblogic container (check Setup guides)
A Java Web Application, you can use the sample application distributed with JOSSO for testing purposes.

We will use the same environment variables previously configured during setup.

Make your Java web application become a JOSSO Single Sign-On partner application

Configure the JOSSO Agent

The Weblogic 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: $DOMAIN_HOME, check
Weblogic setup guides for details.

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>

  <class>org.josso.wls92.agent.WLSSSOAgent</class>
  <gatewayLoginUrl>http://localhost:7001/josso/signon/login.do</gatewayLoginUrl>
  <gatewayLogoutUrl>http://localhost:7001/josso/signon/logout.do</gatewayLogoutUrl>
  <service-locator>
    <class>org.josso.gateway.WebserviceGatewayServiceLocator</class>
    <endpoint>localhost:7001</endpoint>
  </service-locator>
  <partner-apps>

      <partner-app>
          <context>/partnerapp</context>
      </partner-app>

      <partner-app>
          <context>/otherPartnerapp</context>
      </partner-app>

  </partner-apps>
</agent>

You should replace localhost:7001 with the host name 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:7001/partnerapp and http://localhost:7001/otherPartnerapp

Remember to add an entry in the $DOMAIN_HOME/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>/wls-login-redirect.jsp</form-login-page>
            <form-error-page>/wls-login-redirect.jsp</form-error-page>
        </form-login-config>
    </login-config>

    <security-role >
        <description>The Role1</description>
        <role-name>role1</role-name>
    </security-role>

    <security-role >
        <description>The Role2</description>
        <role-name>role2</role-name>
    </security-role>


</web-app>

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.

Now, we need to add a new descriptor required by Weblogic, mapping application roles to server defined principals, in our example they have the same name :

<?xml version="1.0" encoding="UTF-8"?>
<weblogic-web-app
  xmlns="http://www.bea.com/ns/weblogic/90"
  xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd">

  <security-role-assignment>
    <role-name>role1</role-name>
    <principal-name>role1</principal-name>
  </security-role-assignment>

  <security-role-assignment>
    <role-name>role2</role-name>
    <principal-name>role2</principal-name>
  </security-role-assignment>


</weblogic-web-app>

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 more information about integrating EJBs to with the Single Sign-On infrastructure you can browse the sample online from our SVN 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/wls-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" %>
<!--
Redirects the user to the propper login page.  Configured as the login url the web.xml for this application.
-->
<%
    response.sendRedirect(request.getContextPath() + "/josso-wls/josso_login.jsp");
%>

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.

Now you have to copy or create three JSP pages in your web application:

• /josso-wls/josso_login.jsp
• /josso-wls/josso_logout.jsp
• /josso-wls/josso_security_check.jsp

This pages do nothing and they should never execute, they just return a HTTP code 404 NOT FOUND. The JOSSO agent will intercept requests to this specific resources and act accordingly. They are only here because Weblogic requires the resources to exists when redirecting to them from wls-login-redirect.jsp. The files are provided with JOSSO distribution but if you want to write them your self, here is the code which is the same for all of them:

<%response.sendError(javax.servlet.http.HttpServletResponse.SC_NOT_FOUND);%>

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" %>
<html>
 ...
        <a href="<%=request.getContextPath() + "/josso-wls/josso_logout.jsp"%>LOGOUT</a>
...
</html>

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 and WEB-INF/weblogic.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 file.

Deploy the Partner Application

In case of using Weblogic in development mode, you can drop your WAR or EAR file in $DOMAIN_HOME/autodeploy/

Testing it

Contact the Partner application

Using your web browser, contact the following url : *http://localhost:7001/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:7001/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>&nbsp;
    <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>&nbsp;
        <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