Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Chapter 13
Client Detection ServiceThe Sun Java System Access Manager 6 2005Q1 Authentication Service has the capability of being accessed from many client types, whether HTML-based, WML-based or other protocols. In order for this function to work, Access Manager must be able to identify the client type. The Client Detection Service is used for this purpose. This chapter offers information on the service, and how it can be used to recognize the client type. It contains the following sections:
OverviewThe Access Manager Authentication Service has the capability to process requests from multiple browser type clients. Thus, the service can be used to authenticate users attempting to access applications based in HTML, WML or other protocols.
The client detection API can be used to determine the protocol of the requesting client browser and retrieve the correctly formatted pages for the particular client type.
Note
Out of the box, Access Manager only defines client data for supported HTML client browsers. A list of supported browsers can be found in Chapter 1, "Introduction" under the section Client Browser Support.
Client Detection Process
Since any user requesting access to Access Manager must first be successfully authenticated, browser type client detection is accomplished within the Authentication Service. When a client’s request is passed to Access Manager, it is directed to the Authentication Service. Within this service, the first step in user validation is to identify the browser type using the User-Agent field stored in the HTTP request.
The User-Agent information is then matched to browser type data defined and stored in the amClientData.xml file.
Caution
User-Agent information is defined in amClientData.xml but this information is stored in Directory Server under Client Detection Service.
Based on this Client Data, correctly formatted browser pages are sent back to the client for authentication (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 Access Manager services. (If there is no matching client data, the default type is returned.)
Note
The userAgent must be a part of the client data configured for all browser type clients. It can be a partial string or the exact product token.
Enabling Client Detection
By default, the client detection capability is disabled; this then assumes the client to be of the genericHTML type (For example Access Manager will be accessed from a HTML browser). The preferred way to enable the Client Detection Service is to use the Access Manager console and select the option in the Client Detection Service itself. For more information, see the Sun Java System Access Manager Administration Guide. To enable client detection using the amClientDetection.xml, the iplanet-am-client-detection-enabled attribute must be set to true. amClientDetection.xml must then be deleted from Directory Server and reloaded using amAdmin. The following procedure illustrates the complete enabling process.
- Import client data XML file using the amadmin command /IdentityServer_base/SUNWam/bin/amadmin -u amadmin_DN -w amadmin_password -t name_of_XML_file
This step is only necessary if the client data is not already defined in amClientData.xml. The XML file is based on the The sms.dtd Structure of Chapter 8, "Service Management."
- Restart Access Manager.
- Login to Access Manager console.
- Go to Service Configuration and click the ClientDetectionproperties.
- Enable Client Detection.
- Make sure the imported data can be viewed with Access Manager console.
Click on the Edit button next to the Client Data attribute.
- Create a directory for new client type and add customized JSPs.
Create a new directory in /IdentityServer_base/SUNWam/web-src/services/config/auth/default/ and add JSPs for the new client type. Code Example 13-1 is a login page written for a WML browser.
Client DataIn order to detect client types, Access Manager needs to recognize their identifying characteristics. These characteristics identify the features of all supported types and are defined in the amClientData.xml service file. The full scope of client data available is defined as a schema in amClientData.xml. The configured Access Manager client data available for HTML-based browsers is defined as sub-configurations of the overall schema: genericHTML and its parent HTML.
Note
Parent profiles (or styles, as they are referred to in the Access Manager console) are defined with properties that are common to its configured child devices. This allows for the dynamic inheritance of the parent properties to the child devices making the device profiles easier to mange.
HTML
HTML is a base style containing properties common to HTML-based browsers. It might have several branches including web-based HTML (or genericHTML), cHTML (Compact HTML) and others. All configured devices for this style could inherit these properties which include:
- parentId—identifies the base profile. The default value is HTML.
- clientType—an arbitrary string which uniquely identifies the client. The default value is HTML.
- filePath—is used to locate the client type files (templates and JSP files). The default value is html.
- contentType—defines the content type of the HTTP request. The default value is text/html.
- genericHTML—defines a client that will be treated as HTML. The default value is true.
Note
This attribute does not refer to the similarly named genericHTML style.
- cookieSupport—defines whether cookies are supported by the client browser. The default value is true which sets a cookie in the response header. The other two values could be False which sets the cookie in the URL and Null which allows for dynamic cookie detection. In the first request, the cookie is set in both the response header and the URL; the actual mode is then detected and set from the subsequent request.
Note
Although the Client Detection Service supports a cookieless mode, Access Manager console does not. Therefore, enabling this function will not allow login to the console. This feature is provided for wireless applications and others that will support it.
- CcppAccept-Charset—defines the character encoding used by Access Manager to send a response to the browser. The default value is UTF-8.
genericHTML
genericHTML is a configured device that inherits properties from the HTML style as well as defining its own properties. It refers to a HTML browser (Netscape Navigator, Microsoft® Internet Explorer, or Mozilla). Its properties include:
- parentId—identifies the base profile for the configured device. The default value is HTML.
- clientType—an arbitrary string which uniquely identifies the client. The default value is genericHTML.
- userAgent—a search filter used to compare/match the user agent defined in the HTTP header. The default value is Mozilla/4.0.
- CcppAccept-Charset—defines the character encoding set supported by the browser. The default values are UTF-8;ISO-8859-1;ISO-8859-2;ISO-8859-3;ISO-8859-4;ISO-8859-5;ISO-8859-6;ISO-8859-7;ISO-8859-8;ISO-8859-9;ISO-8859-10;ISO-8859-14;ISO-8859-15;Shift_JIS;EUC-JP;ISO-2022-JP;GB18030;GB2312;BIG5;EUC-KR;ISO-2022-KR;TIS-620;KOI8-R.
Client Detection APIAccess Manager is packaged with a Java API which can implement the client detection functionality. The client detection API are in a package called com.iplanet.services.cdm. This package provides the interfaces and classes needed to retrieve client properties. The client detection procedure would include defining the client type characteristics (as stated in Client Data) as well as implementing the client detection API within the external application.
The client detection capability is provided by ClientDetectionInterface, a pluggable interface (not an API invoked by a regular application). It provides a getClientType method. The getClientType method extracts the client data from the browser’s incoming HttpRequest, matches the user agent information and returns the ClientType as a string. Upon successful authentication, the client type is added to the user’s session token. The ClientDetectionException handles any error conditions.