Index

Index
Introduction
Prerequisites
Make your Java web application become a JOSSO Single Sign-On partner application
Set up Security Constraints (JEE)

Web application Security Constraints (web.xml)
EJB Security Constraints (ejb-jar.xml)

Prepare your application
Test it

Contact the Partner application
Authenticate
Access the partner application

Using the Custom User Properties Feature
For more information
Comments

Introduction

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.

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

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.

josso-agent-config.xml

...
<agent:partner-apps>
    <agent:partner-app id="MyPartnerApp" context="/simple-partnerapp"/>
    <agent:partner-app id="MyPartnerOtherApp" context="/otherPartnerapp" />
</agent:partner-apps>
...

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

Set up Security Constraints (JEE)

Web application Security Constraints (web.xml)

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:

<!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>

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).

EJB Security Constraints (ejb-jar.xml)

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.

EJB 3.0

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:

ejb-jar.xml

<?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 http://josso.svn.sourceforge.net/viewvc/josso/branches/JOSSO_1_8_0_B/josso/examples/

Prepare your application

Your container may require specific descriptors or configuration, take a look at the following index to see a quick setup for your platform:

Test it

Contact the Partner application

Hostname

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*.

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

About

Enterprise Edition

Services

Community

JOSSO 2

Setup

Developer Documentation

Deployer Documentation

SSO Plugins

Page Operations

Browse Space

Jossify your JEE Application

Labels: