Added by Gianluca Brigandi, last edited by Sebastian Gonzalez Oyuela on Jan 16, 2009  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Introduction

This guide will walk you through the steps to get a branded gateway created, build up and running. This document is intended to quickly deploy and test branded gateway within a simple single sign-on setting using Tomcat as the target platform.

Branding JOSSO allows you to:

  • Modify JOSSO UI appearance by leveraging Apache's Struts and Tiles framework.
  • Include new resources like JDBC drivers.
  • Include custom JOSSO plugins like stores, etc.
  • Bundle your SSO configuration in the new gateway.
  • More ...

Prerequisites

For creating and deploying branded gateway we will need:

After branding JOSSO, we will install and run tomcat in our Desktop computer to simplify configuration steps.

Creating the Gateway

We will start by creating a new gateway distribution using maven. Let's say we want to create gateway using the java package 'com.test' and 'my-gateway' as the web application name and '0.0.1' as the application's version. We should run the following command:

mvn archetype:create -DarchetypeGroupId=org.josso \
-DarchetypeArtifactId=josso-archetype-gateway \
-DarchetypeVersion=1.8.0 \
-DgroupId=com.test \
-DartifactId=my-gateway \
-Dversion=0.0.1-SNAPSHOT \
-DremoteRepositories=http://repository.josso.org/

Automatic Login

After creating the new branded gateway, you must replace the provided 'AES' key used by automatic (Remember Me) authentication scheme. Edit the file josso-auth.properties from your new project.

Non-Branded Gateway configuration

If you installed a non-branded gateway on your server, make sure to move the gateway configuration resources to your project's resource folder! (All josso-gateway-.xml* files, josso-users.xml and josso-credentials.xml)

A web application maven project will be created in a folder named my-gateway in the current folder.

Project structure looks like this




Branding the Gateway

Next, we'll change the way login page looks. To make it simple, we'll accomplish this by replacing JOSSO logo with our own.
JOSSO logo is located in my-gateway/src/main/webapp/resources/josso-logo.gif. Let's say we have our logo called branded-logo.gif.
First, we'll copy our logo in the same folder as JOSSO logo.
Next, we have to edit josso-layout.jsp page, to change the path to the new logo. josso-layout.jsp is located in my-gateway/src/main/webapp/josso-layout.jsp.

Snippet of josso-layout.jsp:

<html:html>
<head>
	...
</head>
<body>
    <table width="100%" border="0" cellpadding="0" cellspacing="0" >
        <tr>
            <td colspan="2"><a href="http://www.josso.org"  ><html:img page="/resources/josso-logo.gif" border="0"/></a></td>
        </tr>
        ...
    </table>
</body>
</html:html>

We'll change

<html:img page="/resources/josso-logo.gif" border="0"/>

with

<html:img page="/resources/branded-logo.gif" border="0"/>.

That will change JOSSO logo in our branded one.

Next thing to do will be to build the branded gateway.

Building the Gateway

In command line switch to branded gateway's root folder, e.g. under Windows c:\my-gateway and type:

c:\my-gateway>mvn install

This will install the branded gateway war in your local maven repository (for later use by deployment console).

Installing the Gateway

Branded gateway is installed the same way as JOSSO gateway, from JOSSO's Deployment Console. For detail information on starting Deployment Console, take a look at Quick Start.

Run the gateway install command. For details on this command refer to JOSSO Deployment Console.

josso> gateway install --target c:/apache-tomcat-6.0.18 --platform tc60 --copy-configuration false --source mvn:com.test/my-gateway/0.0.1-SNAPSHOT/war

--copy-configuration tells the Console not to copy JOSSO configuration files since they're already part of the branded gateway war.
--artifact contains maven type URL pointing to the branded gateway. This way Console will install branded gateway directly from your local maven repository.

You should see something like:

josso> gateway install --target c:/apache-tomcat-6.0.18 --platform tc60 --copy-configuration false --source mvn:com.test/my-gateway/0.0.1-SNAPSHOT/war

Deploying Apache Tomcat 6.0.x JOSSO Gateway v.1.8.0

Verify Target Apache Tomcat 6.0.x
Apache Tomcat 6.0.x                                              [OK   ] Directory Layout
CatalinaHome                                                     [OK   ]

Install JOSSO Gateway Configuration
Backup and remove existing configuration files

Deploy JOSSO Gateway Application
Installing    []                                                 [OK   ] Created file:///c:/apache-tomcat-6.0.18/webapps/josso
Unjar         [my-gateway-0.0.1-SNAPSHOT.war]                    [OK   ] file:///c:/apache-tomcat-6.0.18/webapps

Apache Tomcat 6.0.x JOSSO Gateway v.1.8.0
Overall Installation                                             [OK   ] Successfull!

Congratulations! You successfully installed the gateway.
Now Follow the JOSSO Gateway Configuration guide and setup JOSSO for your needs!

josso>

Running

Now exit the deployment console and start Tomcat. You have to go to Tomcat's bin folder and run catalina script.

In Windows Systems

c:\> cd apache-tomcat-6.0.18\bin
c:\> catalina run
Using CATALINA_BASE:   C:\apache-tomcat-6.0.18
Using CATALINA_HOME:   C:\apache-tomcat-6.0.18
Using CATALINA_TMPDIR: C:\apache-tomcat-6.0.18\temp
Using JRE_HOME:        c:\jdk1.5.0_13
06/01/2009 15:06:32 org.apache.tomcat.util.digester.SetPropertiesRule begin
...
06/01/2009 15:06:37 org.apache.catalina.startup.Catalina start
INFO: Server startup in 4974 ms

In Unix Systems
$ cd apache-tomcat-6.0.18/bin
$ ./catalina.sh run
Using CATALINA_BASE:   /opt/apache-tomcat-6.0.18
Using CATALINA_HOME:   /opt/apache-tomcat-6.0.18
Using CATALINA_TMPDIR: /opt/apache-tomcat-6.0.18/temp
Using JRE_HOME:       /opt/jdk1.5.0_13
Jan 6, 2009 3:09:18 PM org.apache.catalina.core.AprLifecycleListener init
...
Jan 6, 2009 3:09:26 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 7916 ms

Testing

Now access the branded gateway application at http://localhost:8080/josso/signon/login.do
Login using user1/user1pwd
Both login page and login result page contain branded logo we used. That's all!

Next 2 screenshots show the difference between original JOSSO login page and branded login page

Original JOSSO login page


 
And this is login page of our branded gateway