Added by Sebastian Gonzalez Oyuela, last edited by Sebastian Gonzalez Oyuela on Sep 04, 2009  (view change)

Labels:

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

Index

Introduction

This guide will show you how to use your own login form integrated to any of your partner applications. The process is very simple, you have to follow this steps:

1. Create/Modify your own login form

2. Configure this form as JOSSO Login screen

3. Use login/logout links within your applications

Setup

Let's start by creating a new form as part of our Java sample application.

Create/Modify your Login Form

You have to create/modify your login form so that credentials and other information is properly sent to the gateway authentication service.

Configure your login form as an ignored web resource!

It is very important that you mark your login form URL as an ingnored web resource in the partner application configuration. This varies from agent to agent, take a look at josso-agent-config.xml.

Form Action

The form action to be used is a specific URL handled by local JOSSO Agent. In this example we're creating a login URL for a JOSSO Tomcat agent. Each agent URL varies depending on container specific requirements, see some examples bellow, the list is not complete, check other agents for more URLs:

Form Action Agent Platform
/<context-path>/josso_authentication/ All JBoss, Geronimo, Websphere CE and Tomcat
/<context-path>/josso-wls/josso_authentication.jsp All Weblogic
Result of jossoCreateAuthenticationUrl() functio PHP

Form Fields

Field Hidden Required Description Value
josso_cmd true true Tells JOSSO Gateway what to do, in this case to perform a login login
josso_username false true The login name used as credential to authenticate the user user provided
josso_password false true The secret used as credential to authenticate the user user provided
josso_back_to true false Tells JOSSO Gateway where the agent associated with this application is listening for security checks returned by jossoSecurityCheckUrl() function
josso_on_error true false Tells JOSSO Gateway where to redirect the user if an authentication error occurs, for example wrong password. Should be this form URL

Sample Custom Login Form

myloginform.jsp
<html>
<body>

    <% // Check if we have to display error information
       if (request.getParameter("josso_error_type") != null) { %>
        <font color="red">Invalid login information</font>
    <% } %>

    <form name="jossoLoginForm" method="post" action="<%=request.getContextPath()%>/josso_authentication/">
        <input type="hidden" name="josso_cmd" value="login">
        <table border="0" cellpadding="0" cellspacing="5">
            <tr><td>username:</td><td><input type="text" name="josso_username" size="10"></td></tr>
            <tr><td>password:</td><td><input type="password" name="josso_password" size="10"></td></tr>
            <tr><td colspan="2" align="center"><input type="submit" value="Login" ></td></tr>
        </table>
    </form>
    </p>
</body>
</html>

Displaying login errors

The gateway will send the user back to the login form when authentication fails. Error condition is signalled usgin the HTTP request parameter josso_error_type. If user credentials are invalid, the parameter has the AUTH_ERROR value, otherwise it contains the Java Exception simple class name associated with the error.

Configure the Gateway

The easiest way to configure your own login form is to set the customLoginURL property for the Gateway web configuration. Edit the file josso-gateway-web.xml, in this example the custom login form is located at *http://mycompany.com/myloginform.jsp*

josso-gateway-web.xml
<s:beans xmlns:s="http://www.springframework.org/schema/beans"
       xmlns="urn:org:atricore:josso2:core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
        urn:org:atricore:josso2:core http://www.atricore.org/schema/josso2/josso-core.xsd">

    <web-configuration id="josso-web-configuraiton"
                       rememberMeEnabled="true" 
                       sessionTokenOnClient="false"
                       sessionTokenSecure="false"
                       customLoginURL="http://mycompany.com/myloginform.jsp">

        <!-- List of trusted host names where partner applications are deployed
        <trustedHosts>
            <s:value>localhost</s:value>
        </trustedHosts>         
        -->

    </web-configuration>
    
</s:beans>

Use SSO Login/Logout links within your applications

When you want to create login/logout links in your application's menu or navigation bar for example, you should use specific values handled by your application's local agent. This decouples your code from gateway specific location.
Let's take a look at some examples:

Login URL Logout URL Agent Platform
/<context-path>/josso_user_login/ /<context-path>/josso_logout/ All JBoss, Geronimo, Websphere CE and Tomcat
/<context-path>/josso_user_login.jsp /<context-path>/josso_logout.jsp All JBoss, Geronimo, Websphere CE and Tomcat
Result of jossoCreateLoginUrl() functio PHP

Summary

This guide shows an easy way to brand your login form and how to integrate it with your applications. If you want to further customieze JOSSO by adding your own plug-ins and resources or modifying other UI compontes, take a look at Branding JOSSO documentation.

Examples

For further details on platform specific setup, take a look at josso examples found inside the samples folder provided with JOSSO Distribution.