Sun Java System Calendar Server 6 2005Q4 Developer's Guide

Chapter 3 Proxy Authentication SDK Overview

This chapter describes the Calendar Server Proxy Authentication SDK (authSDK). It addresses the following topics:

Who Will Use the authSDK?

Programmers, whose installation has a portal service, can use authSDK to integrate the portal with Calendar Server. When a portal system authenticates a user, authSDK functions notify Calendar Server, which then allows the user access to various services without reauthentication.

What Is the authSDK?

The authSDK consists of a DLL or shared-object that exports five functions.

The install package includes the following, located in cal_svr_base/bin/authsdk:

Architecture

The authSDK is pretty simple. It consists of initialization, lookup, and cleanup. Additionally, one other function, Function: CEXP_SetHttpPort, allows the authSDK to use a nonstandard port, and another, Function: CEXP_GetVersion, gets the authSDK version number should you need to contact customer or technical support. For a complete description of the API functions, see Chapter 4, Proxy Authentication SDK Reference.

Initialization

Call Function: CEXP_Init for initialization. If you pass it LDAP information, it initializes an LDAP connection used during the lookup phase for discovering on which calendar server the user resides. This connection is set up for a threaded environment. All threads share this connection, but since the locking is done in the LDAP, it is fast enough in most environments. The connection is kept open so there is no set up or tear down cost per lookup.

Other things set up by initialization include the programmer supplied attribute to use for matching the lookup user name in LDAP queries.

Lookup

Use the lookup function, Function: CEXP_GenerateLoginURL, when you want to generate a new session for a user. Lookup performs no authentication. It generates an entry in the session table for the user name and IP address, and returns a URL associated with that session.

If you pass the hostname of a calendar server, the function contacts that server to generate the session. If not, it queries the LDAP server to determine the host.

To generate a session without actually authenticating the user, you must provide the proxy administrator’s ID and password.

Cleanup

If you are in a threaded environment, and you want to clean up resources, such as memory and open LDAP connections, use CEXP_Shutdown.

Functions Overview

The SDK consists of five functions in the SDK, as listed in the following table.

Table 3–1 Proxy Authentication SDK Functions

Function  

Description  

Function: CEXP_GenerateLoginURL

Generates a URL with the valid session ID. 

Function: CEXP_GetVersion

Generates the version ID string. 

Function: CEXP_Init

Initializes the SDK. 

Function: CEXP_SetHttpPort

Specify the port over which you want to contact the calendar server. 

CEXP_Shutdown

Performs all shutdown procedures, including freeing memory and shutting down connections.