Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messenger Express 2004Q2 Customization Guide 

Chapter 5
Managing Authentication to the Sun Java System Messenger Express Service

This chapter describes how to integrate alternative authentication mechanisms with Messenger Express.

This chapter contains the following sections:


Introduction to Authentication

Some sites deploying Messenger Express might want to provide an alternative method of authenticating users. These sites might have portal service in which users sign on once at the “front door” to use various services without reauthentication. In this environment, the Messenger Express login mechanism has to recognize that the other service has already performed the authentication and recognize the user based on credentials provided by the other service.

This is known as proxy authentication. In most cases, users enter a user name and password to access the site. One of the services users can access from the site would be the Messenger Express. When users click on the link to open Messenger Express, it does not ask for a username or password again, because with proxy authentication the user name and password provided at the initial site login is referenced.

The Messenger Express authentication SDK (Software Development Kit) provides the following three components, which can be modified to accept the proxy authentication:


SDK Files and Functions

To integrate the authentication SDK into the existing code, include the expapi.h header file into the calling code and link with the shared library (.dll or .so file). On some platforms, the authentication SDK may also require to link with other system libraries.

Table 5-1 lists the contents of msg_svr_base/bin/msg/authsdk (the install package).

Table 5-1  Contents of authsdk

Files

Function

libexpress.so or DLL

The SDK library

cgiauth.c

Source code for sample CGI using the API

expapi.h

Header file for API users

login.html

HTML source for the sample code

nsapiauth.c

Source code for the sample NSAPI plug-in using API

README

A readme documenting the API and use

login.cgi

Compiled CGI file

Makefile.sample

Example makefile to build login.cgi


SDK Configuration Initialization

The EXP_Init function initializes the SDK configuration information needed when calling other functions:

int EXP_Init(

char *pszLdapHost,

char *pszLdapMatchAttrib,

char *pszLdapDN,

unsigned int iLdapPort,

char *pszLdapBindUser,

char *pszLdapBindPass,

char *pszAdminUser,

char *pszAdminPassword);

Table 5-2 lists the SDK code variables and their description.

Table 5-2  SDK Code Variable Description

SDK Code Variables

Description

pszLdapHost

A null-terminated string containing the host name or IP address of the LDAP server in which the user search is performed.

pszLdapMatchAttrib

A null-terminated string specifying which LDAP attribute the pszAdminUser parameter should be matched against when searching the LDAP. The default is User ID (uid).

pszLdapDN

A null-terminated string specifying the Domain Name (DN) to use when searching for users.

iLdapPort

An integer specifying the port number in which the LDAP server is listening.

pszLdapBindUser

The string specifies the bind DN (Distinguish Name) and password for the directory server. If this is NULL, the SDK attempts to bind as anonymous user.

pszLdapBindUser

The string specifies the bind DN and password for the directory server. If this is NULL, the SDK attempts to bind as anonymous user.

pszAdminUser

The pointer to the string containing the “proxy” username and password is used when connecting to the messaging server. This is not NULL.

pszAdminPass

The pointer to the string containing the “proxy” username and password is used when connecting to the messaging server. This is not NULL.

A successful initialization, returns 0. If initialization fails, a non-zero number is returned. If initialization fails, errno is set to the most appropriate value possible based on what failed (in most cases a system call). These codes then map to standard errno values.


SDK Lookup

The following functions are used to generate a session handle for a specific user and client IP address:

int EXP_GenerateLoginURL(

char *pszUser,

char *pszClientAddress,

char *pszMailHost,

char *pszURL);

Table 5-3  SDK Code Variable Description

SDK Code Variables

Description

pszUser

A null-terminated string containing the user ID (uid).

pszClientAddress

The string representation of the client’s IP address.

pszMailHost

A null-terminated string containing the hostname or IP address of the user’s mail server.

If the third parameter is NULL, the LDAP server (from EXP_init()) is searched to determine this host. Otherwise, the mail host specified is used.

pszURL

The buffer allocated by the caller function in which URL is returned. The URL can have a maximum of 2048 characters long (including terminating NULL).

The function returns 0 on successful initialization, or a non-zero number on failure of initialization. On failure, errno is once again set to the most appropriate value.

The string returned by these functions is a login URL to be used when connecting to Messenger Express. Authentication applications (such as a login CGI) should call these functions after successfully authenticating the user based on the local authentication criteria. A typical CGI would use the resulting string to launch a URL or set a cookie on the client through HTTP headers or JavaScript.


SDK Cleanup

The following function is called to shut down and clean up any resources used by the SDK:

int EXP_Shutdown()

Typically it is not necessary to call the EXP_Shutdown() function in a simple CGI, but if the SDK is used as a plug-in in a continuous server running environment (such as Portal Server) the EXP_Shutdown() is called to reclaim the resources.

The function returns a 0 on successful initialization or a non-zero number indicating failure, and errno is then set to the most appropriate value based upon what failed. These codes also map to standard errno values.

The following function returns a const pointer to a null-terminated string identifying the version number of the SDK being used:

const char*EXP_GetVersion()

The value returned by the EXP_GetVersion() function should not be used in any dependant manner. In other words, do not write programs that expects this string to be in a certain format or contain a certain value. This string is only available to provide information on the version number of the SDK being used.

If no information on the version number is available, the function returns NULL.

The following function can be used to tell the SDK to contact a non-standard port when connecting to the Messenger Express service to generate a session:

void EXP_SetHttpPort

(init iHttpPort)

By default the SDK contacts the standard HTTP port, 80. This function is not thread safe and sets a global value. If you want to use it in a thread environment, lock the call and call the function EXP_GenerateLoginURL.


Example Deployment

The following example explains how the Proxy Authentication can be used. Use this example as a reference point to decide how to use the SDK in your environment.

If everything is set up correctly, upon running the script within a web browser, the CGI script presents the user with a simple Login screen based on the login.html file. If a user enters a valid username and password, the script launches a Messenger Express session without Messenger Express prompting the user to reauthenticate.



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.