Writing a Pluggable SSO Module for Convergence

h1. Writing a Custom SSO Module for Convergence

This chapter describes how to write a pluggable custom Single Sign-On (SSO) module for Sun Convergence. Convergence offers two Single Sign-on mechanisms:
* Access Manager SSO (Legacy Mode and Realm mode). For details, see [How do I set up Access Manager SSO?|Sun Convergence Administrative Tasks#am_setup_sso_legacymode]
* Messaging SSO (also referred to as Trusted Circle SSO). For details, see [Single Sign-on|Sun Convergence Administrative Tasks#single_signon].

* All custom SSO modules must implement SSOProvider interface.
* Convergence uses LDAP ( Schema 1 or Schema 2) to store user data. This is called UG LDAP.
* UG LDAP uses the LDAP filter to identity user in UG LDAP.
* The SSO provider must provide the UG LDAP user identifier and domain identifier.
* After SSO validation the implementation must provide valid {{uid}} and valid domain/organization of the user in UG LDAP. This information will be obtained by SSO framework by invoking {{getUid()}} and {{getDomain()}} method of custom SSO Provider.
* The SSO implementation can use any other class that requires custom SSO module to work.

To write a custom SSO module:
# Convergence defines a set of interfaces and class that need to be implemented. They are:
\\
#* {{SSOProvider.java}}
#* {{SSOListner.java}}
# Configure the SSO module using the {{iwcadmin}} command-line utility.





{code:title=SSOProvider.java}
package com.sun.comms.client.security.sso;

import java.util.Properties;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
* Custom SSO provider must implement this interface.
*/
public interface SSOProvider {
/**
* SSO framework in Convergence will invoke this method by passing all required SSO configuration, that are configured in configuration.
* Implementation can store this info for future use. keys in initConfig are case sensitive.
*/
public void init(Properties initConfig);

/**
* This method will be invoked by SSO framework after calling init() method. Implementation can have SSO validation code here.
* If SSO validation or Single-Sign-On is successful, this method should return true.
* If SSO validation succeeds implementation must not create http session here. It is taken care by SSO framework
*/
public boolean SingleSignOn(HttpServletRequest request,HttpServletResponse response) throws SingleSignOnException;

/**
* This method will be invoked by SSO framework when user logs out of application and Single-Sign-Off is enabled in configuration.
* If SSO validation or Single-Sign-Off is successful, this method should return true.
* Implementation can perform SSO provider specific Single-Sign-Off here like cleanup SSO cookies in response.
*/
public boolean SingleSignOff(HttpServletRequest request,HttpServletResponse response) throws SingleSignOffException;

/**
* This method will be called by SSO framework if Single-Sign-On succeeds. Implementation must provide a uid (user identifier) of the user
* in UG LDAP. This will be used by framework to load authenticated user from UG LDAP.
*/
public String getUid();

/**
* This method will be called by SSO framework if Single-Sign-On succeeds. Implementation must provide a domain/organization (domain identifier) of the user
* in UG LDAP. Framework will use this to locate the user under this domain in UG LDAP.
*/
public String getDomain();

/**
* How much more time SSO token is valid with SSO Provider. Currently not used by framework and hence can be ignored.
*/
public long getTimeLeft();


}
{code}
{code:title=SSOListener.java}
package com.sun.comms.client.security.sso;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

/*
* If SSO provider needs to perform some post Single-Sign-On operation. This interface must be implemented.
*/
public interface SSOListener {
/**
* This method will be invoked by framework if Single-Sign-On operation succeeded, user entry is loaded and http session is created.
* Implementation can do postSignOn related tasks here e.g. registering token listener for sso token notification etc.
*
* @param request - Http request for single sign on
* @param response - Http response for single sign on
* @param session- Convergence session that is created after successful single sign on
*/
public void postSignOn(HttpServletRequest request,HttpServletResponse response,HttpSession session);

}
{code}
SingleSignOffException - Exception thrown if SingleSignOff fails for any abnormal condition.

SingleSignOnException - Exception thrown if SingleSignOn fails for any abnormal condition.
{note:title=Note}While implementing the custom SSO module, {{iwc.jar}} should be available in the classpath of development environment. The {{iwc.jar}} file requires SSO module classes.

# Configure the SSO module using the {{iwcadmin}} command:
{code}
iwcadmin -W /location/pwdFile -o sso.enable -v "true"
iwcadmin -W /location/pwdFile -o sso.enablesignoff -v "true"
iwcadmin -W /location/pwdFile -o sso.ssoserviceimpl -v "com.client.sample.CustomSSOProvider"
iwcadmin -W /location/pwdFile -o sso.misc.<configname1> -v "ConfigVal1"
iwcadmin -W /location/pwdFile -o sso.misc.<cofnigname2> -v "ConfigVal2"
{code}
{note:title=Note}All the miscellaneous configuration parameters such as {{<configname1>}} and {{<configname2>}} are case sensitive. These parameters should match the in the {{SSOProvider}} classes' {{init()}} method.
{note}
# Create a jar file with all custom classes and supporting classes.

* {{SSOProvider}}
* {{SSOListener}}
Additionally, you can also use other classes that help you to implement the SSO module. Finally, you need to configure Convergence to use the custom SSO module that you created using the {{iwcadmin}} command.