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

• 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. 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:

• Initialization

• Lookup

• Cleanup

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
libexpress.so/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 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);

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 to search for users.
pszLdapMatchAttrib	A null-terminated string specifying which LDAP attribute the pszAdminUser parameter should be matched against when searching 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 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.

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

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 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:

const char*EXP_GetVersion()

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:

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.