Previous Contents Index Next |
iPlanet Messenger Express 5.2 Customization Guide |
Chapter 5 Managing Authentication to the Messenger Express Service
This chapter describes how to integrate alternative authentication mechanisms with iPlanet Messenger Express.This chapter contains the following sections:
Introduction to Authentication
Introduction to Authentication
Some sites deploying Messenger Express might want to provide an alternative method of authenticating users. Most of these sites have some sort of portal service in which users sign on once at the "front door" to use various services without reauthentication. In this case, the Messenger Express' login mechanism can recognize that this other service has already performed the authentication and recognizes the user based on credentials provided by the authenticator.This is known as proxy authentication. In most cases, users go to a Web page, type in a user name and password, and then enter 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 is not necessary to 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, begin by including the expapi.h header file into the calling code and link with the DLL/shared object. On some platforms, the authentication SDK may also require linking with other system libraries.Table 5-1 shows the contents of server-root/bin/msg/authsdk (the install package).
Table 5-1    Contents of authsdk
Files
Function
SDK Configuration Initialization
The following 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);
Upon successful completion, a 0 is returned. If initialization fails, a non-zero number is returned. If failure occurs, 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:Typically it is not necessary to call in a simple CGI, but plug-ins using the API might want to reclaim resources and continue running.
The function returns a 0 upon 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:
The value itself should not be used in any dependant manner. In other words, do not code anything that expects this string to be in a certain format, contains a certain value, and so on. This string is only available to provide information to support about which version you are using.
If no version number information 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:
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:
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.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:
Compile the cgiauth.c file into an executable CGI file and configure an HTTP server to execute the newly compiled CGI file.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated February 28, 2002