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

Part II Proxy Authentication SDK

This part covers the Proxy Authentication SDK and contains the following chapters:

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. 

Chapter 4 Proxy Authentication SDK Reference

This chapter describes the Calendar Server Proxy Authentication SDK (authSDK) API. The chapter contains a section for each of the following five authSDK functions and a section on How to Use the authSDK:

Function: CEXP_GenerateLoginURL

Purpose

Returns a login URL with a valid session ID for a given user.

Syntax

int CEXP_GenerateLoginURL (char * pszUser,
                           char * pszClientAddress,
                           char * pszCalendarHost,
                           char * pszURL);

Parameters

pszUser

A string containing the user name. 

pszClientAddress

A string containing the client host IP-address. 

pszCalendarHost

A string containing the hostname (no IP-address) of the calendar server. 

pszURL

A pointer to a buffer to place the URL 

Returns

Returns 0 on success, -1 on failure. On success, the pszURL buffer contains a valid URL string.

Function: CEXP_GetVersion

Purpose

Gets the version ID string.

Syntax

char * CEXP_GetVersion(void);

Parameters

None

Returns

A reference to the version ID string.

Function: CEXP_Init

Purpose

Initializes the SDK.

Syntax

int CEXP_Init (char * pszLdapHost,
               char * pszLdapMatchAttrib,
               char * pszLdapDN,
               unsigned int iLdapPort,
               char * pszLdapBindUser,
               char * pszLdapBindPass,
               char * pszAdminUser,
               char * pszAdminPassword);

Parameters

pszLdapHost

A string containing the hostname of the directory server. 

pszLdapMatchAttrib

A string containing the attribute name. Used to match against the user name. 

pszLdapDN

A string containing the base DN to search for user records. “DN”, for Distinguished Name, is a string representation of an LDAP directory entry’s name and location. 

iLdapPort

An integer specifying the directory server’s port number. 

pszLdapBindUser

A string specifying the DN to bind as. 

pszLdapBindPass

A string containing the password for the bind DN. 

pszAdminUser

A string containing the Calendar Server administrator’s LDAP user ID. 

pszAdminPassword

A string containing the Calendar Server administrator’s password. 

Returns

Returns 0 on success, -1 on failure.

Comment

If the bind DN (pszLdapBindUser) and password (pszLdapBindPass) are NULL, anonymous searching is attempted.

Function: CEXP_SetHttpPort

Purpose

Sets the HTTP port used to contact the calendar server.

Syntax

void CEXP_SetHttpPort (int iHttpPort);

Parameters

iHttpPort

An integer specifying the port. 

Returns

Nothing.

CEXP_Shutdown

Purpose

Cleans up all global memory, shuts down connections, and other cleanup functions when the user is finished using the SDK.

Syntax

int CEXP_Shutdown (void);

Parameters

None

Returns

Returns 0 on success, -1 on failure.

Comments

Call this only after all threads using the SDK complete.

How to Use the authSDK

To implement authSDK in your installation, follow these steps:

  1. Link the authSDK to your code.

    To integrate the authSDK into your existing code, include the expapi.h header file in the calling code and link with the DLL or shared-object. On some platforms you might also be required to link with other system libraries the authSDK requires.

  2. Authenticate your user with your portal authentication program.

  3. Call Function: CEXP_Init.

    This function initializes the authSDK configuration information. This is necessary before any other authSDK function is called.

  4. Optionally, call Function: CEXP_SetHttpPort.

    By default, the authSDK contacts the standard HTTP port, 80. Use this function to tell the authSDK to contact a nonstandard port when connecting to generate a session.


    Caution – Caution –

    This function is not thread safe and sets a global value. If you want to use it in a threaded environment, you must lock around this call and the Function: CEXP_GenerateLoginURL call.


  5. Call Function: CEXP_GenerateLoginURL.

    This function generates a session handle for the user and client IP address. It returns a string, in a buffer you allocate, containing a login URL to be used when connecting to Calendar Server. The string is a kind of token providing proof of identity. It is given to the client in the form of a cookie, or URL, inside HTTP headers or JavaScript.TM The client then connects to Calendar Server, presenting the token as proof of identity.

  6. Optionally, call CEXP_Shutdown.

    Call this function to shutdown and cleanup any resources used by the authSDK. It is not necessary to call this function in some environments (a simple login, for example), but plug-ins using the API might want to reclaim resources and continue running.

Other Tips

The following is a list of other things that must be done to assure success in using the AuthSDK: