Chapter 11   Client Detection


The Sun™ One Identity Server may be accessed using multiple clients types, whether HTML-based, WML-based or other protocols. In order for this function to work, Identity Server must be able to identify the client type. The client detection API is used for this purpose. This chapter offers information on the API, and how it can be used to recognize the client type. It contains the following sections:

• Overview

• Client Data

• Client Detection API

Overview

---

Identity Server has the capability to process requests from multiple client type browsers. The client detection API can be used to determine the protocol used by the requesting client browser and retrieve the correctly formatted pages for the particular client type.

---

Note	Currently, Identity Server only defines client data for supported HTML client browsers including Internet Explorer and Netscape Communicator.

---

Since any browser type requesting access to the Identity Server must first be successfully authenticated, client detection is accomplished within the Authentication Service. When a client's HTTP request is passed to the Identity Server, it is directed to the Authentication Service. Within this framework, the first step in user validation is to identify the browser type using information stored in the HTTP string request. The Authentication Service then uses this information to retrieve the browser type's characteristics. The characteristics are configured and stored in the amClientDetection.xml file and are referred to as the client data. Based on this client data, correctly formatted authentication pages are sent back to the client browser (for example, HTML or WML pages). Once the user is validated, the client type is added to the session token (as the key clientType) where it can be retrieved and used by other Identity Server services.

---

Note	The client detection mechanism is disabled by default which assumes the client to be of the genericHTML type. All client data associated with genericHTML, as explained in "Client Data", will be used.

---

Client Data

---

In order to recognize client types, Identity Server stores their identifying characteristics in its Directory Server data store. This client data identifies the features of all of the particular deployment's supported client browsers. Client data for supported client types are defined in the amClientDetection.xml file. The attribute in which it is defined is iplanet-am-client-detection-client-types. The different aspects of the client data are separated by a pipe ("|") as follows:

clientType=<value>|userAgent=<value>|contentType=<value>|cookieSupport=<value>|fileIdentifier=<value>|filePath=<value>|charset=<value>.

The fields defined are:

• clientType—an arbitrary string which uniquely identifies the client. The default is genericHTML.

• UserAgent—a search filter used to compare/match the user-agent defined in the HTTP header. The default is Mozilla/4.0.

• contentType—defines the content type of the HTTP request. The default is text/html.

• cookieSupport—defines whether cookies are supported by the client browser. The default is true.

• fileIdentifier—is not used at this time.

• filePath—is used to locate the client type files (templates and JSP files). The default is html.

• charset—defines the character encoding used by Identity Server to send a response to the browser. The default value is UTF-8. The character set can be configured for any given locale by adding charset_locale=codeset where the code set name is based on the Internet Assigned Numbers Authority (IANA) standard.

  
  

  ---

  Note	In order to enable client detection for the Identity Server deployment, the iplanet-am-auth-client-detection-enabled attribute, also defined in the amClientDetection.xml file, must be set to true.

  ---

  
  

Client Detection API

---

By default, Identity Server only includes client detection functionality for browsers that use HTML. But, it is packaged with an API for writing proprietary client detectors that can retrieve any client data. The client detection API are in a package called com.iplanet.services.cdm. This package provides the interfaces and classes to detect any client browser types. The procedure would include defining the client type characteristics for the new module (as stated in "") as well as implementing the client detection API within the external application. Identity Server services can be accessed by multiple client browser types. For example, a client accessing Identity Server may be a HTML client type or a WML client type. As any client browser requesting access to an Identity Server service must be successfully authenticated, client detection is accomplished as part of the Authentication Service. This service identifies the client type from it's incoming HTTPRequest for access, using the getClientType method in the ClientDetectionInterface interface. Upon successful authentication, the client type is then added to the user's session token where other applications can find it and use the client detection API to retrieve it.

---

Note	The Identity Server Javadocs can be accessed from any browser by copying the complete <identity_server_root>/SUNWam/docs/ directory into the <identity_server_root>/SUNWam/public_html directory and pointing the browser to http://<server_name.domain_name>:<port>/docs/index.html.

---

Client Detection Module Interface

Client detection capability is provided by the ClientDetectionInterface interface. It contains a getClientType method which is called by the Authentication Service when a new login request is received. The Authentication Service executes the retrieval of the value of the iplanet-am-auth-client-detection-class attribute to determine the name of the implementing class of the ClientDetectionInterface. The service then passes the HttpRequest to the getClientType method which does the actual client detection and returns the clientType as a string. The default implementation will assume the client type to be the defined default type. An error condition will be handled by the ClientDetectionException class. Code Example 11-1 below is an example implementation of the ClientDetectionInterface.

---

Code Example 11-1    Implementation of the ClientDetectionInterface  

/**

* $Id: ClientDetectionDefaultImpl.java,v 1.2 2002/05/09 01:27:40 denz Exp $

* Copyright 2001 Sun Microsystems, Inc. Some preexisting

* portions Copyright 2001 Netscape Communications Corp.

* All rights reserved. Use of this product is subject to

* license terms. Federal Acquisitions: Commercial Software --

* Government Users Subject to Standard License Terms and

* Conditions.

*

* Sun, Sun Microsystems, the Sun logo, and iPlanet are

* trademarks or registered trademarks of Sun Microsystems, Inc.

* in the United States and other countries. Netscape and the

* Netscape N logo are registered trademarks of Netscape

* Communications Corporation in the U.S. and other countries.

* Other Netscape logos, product names, and service names are

* also trademarks of Netscape Communications Corporation,

* which may be registered in other countries.

*/

package com.iplanet.services.cdm;

/* iPlanet-PUBLIC-CLASS */

import javax.servlet.http.HttpServletRequest;

import java.util.HashMap;

import com.iplanet.am.util.*;

/**

* The <code>ClientDetectionInterface</code> interface needs to

* be implemented by services and applications serving multiple

* clients, to determine the client from which the request has

* originated. This interface detects the clientType from the client request.

*/

public class ClientDetectionDefaultImpl implements ClientDetectionInterface

{

/** Detects the client type based on the request object

* @param retuest Http Servlet Request

* @return a String representing the client type

* @exception ClientDetectionException when there is an error

* retrieving client data

*/

/* For caching purpose, HashMap is used */

private static HashMap agentTable = new HashMap (10);

private static Debug debug = Debug.getInstance("amClientDetection");

public String getClientType(HttpServletRequest request)

throws ClientDetectionException {

String lstr = request.getHeader("User-Agent");

if (debug.messageEnabled() ) {

debug.message("DefaultImpl Agent = "+lstr);

}

String result;

/* Check if it is in the cache */

result = (String)agentTable.get(lstr);

if (result != null && result.length() != 0) {

return result;

}

result = "genericHTML"; // Set the default value

/* Known formats if User-Agents are

Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) ==> MSIE

Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 4.0) ==> MSIE

Mozilla/4.76 [en] (X11; U; SunOS 5.8 sun4u) ==> NSCP_UNIX

Mozilla/5.0 (X11; U; Linux i686; en-US; rv:0.9.2.1) Gecko/20010901 ==> NSCP_UNIX

Mozilla/4.79 [en] (Windows NT 5.0; U) ==> NSCP_WIN32

Mozilla/4.78 [ja/[Vine,RedHat]] (X11; U; Linux 2.4.7-10 i686) ==> NSCP6

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0) ==> MSIE6

Mozilla/4.78 [en] (WinNT; U) ==> NSCP_WIN32

*/

char[] str = lstr.toCharArray();

String tokens ;

/* Skip leading space */

int idx = 0;

int st;

try {

/* Skip the preceding white spaces */

while (Character.isWhitespace(str[idx])) {

idx++;

}

st = idx;

/* Get the first token */

while (!Character.isWhitespace(str[idx])) {

idx++;

}

String agent = new String (str,st,idx);

/* Look for compatibilty */

while ((str[idx]!='(')) {

idx++;

}

st = idx+1;

while ((str[idx]!=')')) {

idx++;

}

tokens = new String(str,st,idx-st);

if (tokens.indexOf ("MSIE")!= -1) {

if (tokens.indexOf ("6.0")!= -1)

return "MSIE6";

else

result= "MSIE";

} else if(agent.indexOf("Mozilla/4")!= -1) {

if ( (tokens.indexOf ("X11;") != -1) && (tokens.indexOf ("U;")!= -1))

result= "NSCP_UNIX";

if (tokens.indexOf ("Windows") != -1 || tokens.indexOf("WinNT") != -1)

result= "NSCP_WIN32";

} else if ( (agent.indexOf ("Mozilla/5") != -1) )

result="NSCP6";

} catch (IndexOutOfBoundsException ex) {

// Unable to parse the User-Agent or unknown Agent. Fall back to

// Generic HTML

if (debug.messageEnabled() ) {

debug.message("DefaultImpl AgentException in parsing = "+ex);

}

}

if (debug.messageEnabled() ) {

debug.message("DefaultImpl result = "+result);

}

synchronized (agentTable) {

agentTable.put (lstr, result);

}

return result;

}

}