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

• SDK Files and Functions

• SDK Configuration Initialization

• SDK Lookup

• SDK Cleanup

• Example Deployment

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:

• Initialization

• Lookup

• Cleanup

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.

SDK Files and Functions lists the contents of msg_svr_base/bin/msg/authsdk (the install package).

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);

      

SDK Configuration Initialization lists the SDK code variables and their description.

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);

      

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.

• To test the Proxy Authentication API, see the cgiauth.c file. You need to edit certain #define statements appearing at the beginning of the file to suit your configuration:

#define HTML_SOURCE_FILE “login.html”
#define BUFFER_SIZE 1024
#define MAIL_SERVER “mail.yourdomain.com”
#define DIRECTORY_SERVER “directory.yourdomain.com”
#define DN “o=yourdomain.com”
#define ADMINNAME “admin”
#define ADMINPASS “admin”

      

• Change the values for MAIL_SERVER, DIRECTORY_SERVER, DN, ADMINNAME, and ADMINPASS to reflect your configuration. For example, if the mail server is mail.siroe.com, the directory server is ldap.siroe.com, and the administration username and password are sysadmin, then those lines should appear as follows:

#define HTML_SOURCE_FILE “login.html”
#define BUFFER_SIZE 1024
#define MAIL_SERVER “mail.siroe.com”
#define DIRECTORY_SERVER “ldap.siroe.com”
#define DN “o=siroe.com”
#define ADMINNAME “sysadmin”
#define ADMINPASS “sysadmin”

      

• Compile the cgiauth.c file into an executable CGI file and configure an HTTP server to execute the newly compiled CGI file.

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.