Integrating Java Open Single Sign-On in Pluto Blog

Version 2



    JOSSO Architecture: Overview
    Integrating a Single Sign-On Service in Pluto
    Installing Pluto
    Installing JOSSO
    Protecting a Portal Page
    Configuring JAAS
    Running Pluto
    Testing the SSO-Enabled Pluto

    In this article, we will show how to provide single sign-on functionality in Apache's Pluto portlet container. Pluto is the reference implementation of the Java Portlet Specification (JSR 168). Pluto represents a runtime environment for portlets implementing the Portlet API that offers services through portal pages and manages their lifecycle. A portlet is a web component that, based on a request (e.g., an HTTP request), generates a piece of markup (e.g., HTML or WML). The portal is the component that provides application services and, using the portlet container, renders portlet-generated content in a web page. A simple portal component, called the Portal Driver, is included in Pluto and enables portlet container testing.

    JOSSO Architecture: Overview

    JOSSO, or Java Open Single Sign-On, is an open source, J2EE-based SSO infrastructure aimed to provide a solution for centralized, platform-neutral user authentication and authorization.

    JOSSO addresses web single sign-on based on these concepts:

    • Pluggable framework: It provides a component-oriented infrastructure that supports creating and combining multiple authentication scheme, credential, and session stores. For example, supporting certificate-based authentication is only a matter of implementing an authentication scheme component and referencing it from the JOSSO configuration.
    • Tomcat-friendly: JOSSO integrates into any application server, portal infrastructure, or web containers based on Tomcat by configuration and without changing the code base.
    • Transparent integration: Partner web applications integrating to the single sign-on don't need any dependency with a proprietary API. JOSSO handles the whole authentication flow, leaving the identity of the user accessible to web applications and EJB components through the Servlet and EJB APIs, respectively.
    • Cross-platform: It allows for the integration of Java and non-Java applications, such as PHP or Microsoft ASP applications. It uses the standard SOAP over HTTP as the standard communication layer to deliver this cross-platform feature.
    • Commitment to open standards: The security infrastructure is based on JAAS, web services/SOAP, EJB, servlet/JSP and Struts standards.

    JOSSO comprises three main elements:

    • SSO Gateway: This represents the SSO server and provides authentication services to users who need authentication with partner applications.
    • SSO Agent: This represents the client of the SSO Gateway to which authentication requests are delegated on user protected resource access, managing the whole user authentication flow. The SSO Agent validates SSO sessions and obtains associated user information against the SSO Gateway web services using the SOAP protocol.
    • Partner application: This represents a web application that uses SSO Gateway services to authenticate users.

    Figure 1
    Figure 1. JOSSO-Pluto integration high-level architecture diagram

    The flow of a web application integrated to single sign-on through JOSSO is the following:

    1. The user requests a protected resource from a partner application.
    2. The SSO Agent protecting the partner application intercepts the request and, since it is unidentified, redirects the user to the single sign-on form on the SSO Gateway.
    3. The user enters his/her credentials, which, depending on the selected authentication scheme, they may request either a user/password pair or a X.509 Client Certificate.
    4. The SSO Gateway processes the form submission, loads the user's credentials from the configured stores (e.g., LDAP, database) and checks their validity.
    5. If the credentials are valid, the user is authenticated and an SSO session token is generated and saved for his/her session in the session store. The user is then redirected back to the protected resource originally requested.
    6. The SSO Agent protecting the partner application intercepts the request, and using the SSO Gateway JAAS Login module, checks the validity of the session and obtains the authenticated subject from the SSO Gateway using SOAP.
    7. The SSO Gateway picks up the session identifier supplied from the session store and obtains the associated user information from the identity store.
    8. The SSO Agent introduces the authenticated subject returned by the SSO Gateway web service in the HTTP request and handles it to the target web application.
    9. The web application processes the HTTP request and eventually uses the getUserPrincipal() andisUserInRole() standard calls on theHttpServletRequest instance to obtain the identity of the authenticated user to perform additional security assertions.

    Integrating a Single Sign-On service in Pluto

    One of the most common services in portals is a web single sign-on that mainly provides a single user-authentication entry point while maintaining the associated session, along other web applications, and does not need user authentication each time. Multiple authentication schemes are usually supported, such as basic authentication (name and password) and strong authentication using client certificates. User credentials are maintained in a central repository, which is usually an LDAP server, but other persistence mechanisms can be used, such as database or XML files.

    Pluto includes a simple portal implementation called Portal Driver, built on top of the portlet container, that provides minimal services to let portlets run. We'll now focus on the Portlet Entity Registry and the Page Registry. Both are configurable through XML configuration files. The Portlet Entity Registry is used to define portlets available in the portal. The Page Registry is used to define the pages available in the portal, from which portlets are referenced.

    The single sign-on service is implemented using JOSSO, working as a separate web application from Pluto's. The single sign-on Agent is placed in front of the Pluto web application to intercept HTTP requests and, in case of a protected page access, to redirect the user for authentication at the SSO Gateway. Once successfully authenticated, the user is redirected back to the protected portal page he/she initially requested, revealing his identity to the portlet container and associated portlets.

    From the single sign-on perspective, Pluto acts as a partner application where per-portal page security constraints are declared using the standard web.xml file.

    In this article, we use a single-tier configuration, which means that both the SSO Gateway and the SSO Agent reside in the same host. In an n-tier configuration, partner applications are located in potentially different hosts from the SSO Gateway host.

    Installing Pluto

    If you don't have the Pluto portlet container, download it install it. Since JOSSO integration with Pluto doesn't require recompiling Pluto, you can download the binary/bundled version with the Tomcat web container, Pluto portlet container, Portal Driver, and Pluto test suite. Extract the binary distribution into a directory; this will be referred to from now on asPLUTO_HOME.

    Installing JOSSO

    Download the latest JOSSO source distribution from and expand it. Set the CATALINA_HOME environment variable to yourPLUTO_HOME. JOSSO is deployed right there.

    Follow this procedure to install JOSSO in Pluto:

     $ build deploy
     $ build install

    Now install the SSO Agent in front of Pluto by editing the file$PLUTO_HOME/conf/server.xml:

     <Server> ... <Service> ... <Engine> ... <Host> <Valve className="org.josso.agent.SSOAgentValve" debug="1"/> ... </Host> </Engine> </Service> </Server>

    For more information, please check the technical guidelines at the JOSSO web site.

    Protecting a Portal Page

    The default web context in Pluto is /pluto. Portal Pages are referenced by their identifiers in relation to the web context/pluto. Consequently, to access a portal page namedprotected_test, the URL is: http://plutohost:8080/pluto/portal/protected_test. When you access it, this URL displays all of theprotected_page fragments rendered by the corresponding portlets.

    Pluto comes with a portal page called test made up of three fragments. One is a navigation bar and the other two are associated with JSR 168 test-suite portlets.

    Now, make this page accessible only to authenticated single sign-on users associated with role1.

    Edit the file$PLUTO_HOME/webapps/pluto/WEB-INF/data/pageregistry.xmland replace the following line:

    <fragment name="test" type="page">


    <fragment name="protected_test" type="page">

    The next steps are essential to tell the SSO Agent that any Pluto portal page authentication, if required, is handled by JOSSO.

    Create a file in $PLUTO_HOME/bin calledjosso-agent-config.xml, as follows:

    <?xml version="1.0" encoding="ISO-8859-1" ?> <agent> <class>org.josso.agent.CatalinaSSOAgent</class> <gatewayLoginUrl> http://localhost:8080/josso/signon/ </gatewayLoginUrl> <gatewayLogoutUrl> http://localhost:8080/josso/signon/ </gatewayLogoutUrl> <sessionAccessMinInterval>1000</sessionAccessMinInterval> <service-locator> <class>org.josso.gateway.WebserviceGatewayServiceLocator</class> <endpoint>localhost:8080</endpoint> </service-locator> <partner-apps> <partner-app> <context>/pluto</context> </partner-app> </partner-apps> </agent>

    Create a file in $PLUTO_HOME/bin calledjosso-config.xml, as follows:

     <?xml version="1.0" encoding="ISO-8859-1" ?> <configuration> <hierarchicalXml fileName="josso-agent-config.xml"/> </configuration>

    Now the time has come to protect the protected_testportal page. Edit the$PLUTO_HOME/webapps/pluto/WEB-INF/web.xmlfile.

    Enable role1 as the page accessing role replacing:





     <auth-constraint> <role-name>tomcat</role-name> </auth-constraint>


     <auth-constraint> <role-name>role1</role-name> </auth-constraint>

    For the SSO Agent to fully handle the authentication flow, replace:

     <login-config> <auth-method>BASIC</auth-method> </login-config>


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

    Finally, declare the new role by replacing:

     <security-role> <role-name>tomcat</role-name> </security-role>


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

    Now that you have finished, create the JSP previously referenced in the $PLUTO_HOME/webapps/pluto directory with this content:

     <%@page contentType="text/html; charset=iso-8859-1" language="java" session="true" %> <% response.sendRedirect(request.getContextPath() + "/josso_login/"); %>

    Configuring JAAS

    Since the SSO Agent to confirm the SSO session and obtain the authenticated subject uses a Login Module, you have to enable JAAS in Catalina.

    Create a file called jaas.conf in the$PLUTO_HOME/conf directory with the following:

     josso { org.josso.agent.jaas.SSOGatewayLoginModule required debug=true; };

    Now declare the Catalina realm that will provide the authenticated subject information to Pluto. Edit the file$PLUTO_HOME/conf/server.xml:

     <Server> ... <Service> ... <Engine name="Catalina" defaultHost="localhost" debug="0"> ... <Realm className="org.josso.agent.jaas.CatalinaJAASRealm" appName="josso" userClassNames="org.josso.gateway.identity.service.BaseUserImpl" roleClassNames="org.josso.gateway.identity.service.BaseRoleImpl" debug="1" /> ... </Engine> </Service> </Server>

    Running Pluto

    The JOSSO Gateway is preconfigured with a simple authentication scheme using user/password as input credentials, stored in an XML file.

    It has two built-in user accounts:

    user1/user1pwd: Associated to the rolerole1. user2/user2pwd: Associated to the role role2.

    Before running Pluto, tell Pluto where to find the JAAS configuration by setting the JAVA_OPTS variable as follows:


    Change to $PLUTO_HOME/bin and run the following command:

     $ catalina run

    Testing the SSO-Enabled Pluto

    Go to http://localhost:8080/pluto/portal/protected_test.

    You should be redirected to the SSO Gateway to log in. Enteruser1 as the username and user1pwd as the password. Once you authenticate yourself, you can access theprotected_test portal page and its portlets.

    If you open a new browser session and try the same procedure but try to log on with the user2/user2pwdaccount, you should receive an "Access Denied" message, sinceuser2 is associated to role2, notrole1.


    In this article, you have seen how to integrate Java Open Single Sign-On in Apache's Pluto portlet container. If you're in a hurry, you will find a bundle at the JOSSO site with Tomcat 5.0.28, Pluto 1.0.1-rc1, and JOSSO 1.2, which can be downloaded from