Chapter 4   Proxy Authentication SDK Reference


This chapter describes the Sun™ ONE Calendar Server Proxy Authentication SDK (authSDK) API. The chapter is divided into two parts: Proxy Authentication SDK Functions, and How to Use the authSDK.

Proxy Authentication SDK Functions

---

There are five authSDK functions. They are presented below in alphabetical order, not in order of use:

• CEXP_GenerateLoginURL

  Generates a URL with the valid session ID.

• CEXP_GetVersion

  Generates the version ID string.

• CEXP_Init

  Initializes the SDK.

• CEXP_SetHttpPort

  Specifies the port over which you will contact the calendar server.

• CEXP_Shutdown

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

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
There are four 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.

CEXP_GetVersion

Purpose
Gets the version ID string.

Syntax
char * CEXP_GetVersion(void);

Parameters
There are no parameters:

Returns
A reference to the version ID string.

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
There are eight 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 Sun ONE Calendar Server administrator's LDAP user ID.
pszAdminPassword	A string containing the Sun ONE 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 will be attempted.

CEXP_SetHttpPort

Purpose
Sets the HTTP port used to contact the calendar server.

Syntax
void CEXP_SetHttpPort (int iHttpPort);

Parameters
There is one parameter:

iHttpPort

An integer specifying the port.

Returns
Nothing.

CEXP_Shutdown

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

Syntax
int CEXP_Shutdown (void);

Parameters
There are no parameters:

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, simply include the expapi.h header file in the calling code and link with the DLL/shared-object. On some platforms you may also be required to link with other system libraries the authSDK requires.

2. Authenticate your user with your portal authentication program.

3. Call CEXP_Init.

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

4. Optionally, call CEXP_SetHttpPort.

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

   ---

   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 CEXP_GenerateLoginURL call.

   ---

   
   

5. Call 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 the Sun ONE 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 via HTTP headers or JavaScript™. The client will then connect to Sun ONE 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 CGI login, for example), but plug-ins using the API may want to reclaim resources and continue running.

Other Tips

There are a few other things that must be done to assure success in using the AuthSDK:

• The value of service.http.allowadminproxy in the ics.conf file must be "yes".

• The parameter caladmin, passed in the init method, must have the same value as service.admin.calmaster.userid in the ics.conf file.

• The parameter calpass, passed in the init method, must have the same value as service.admin.calmaster.cred in the ics.conf file.

• The two parameters caladmin and calpass must be defined in your directory service.

• If your calendar server is not listening on the default port 80, you must use the SetHttpPort method with the correct port value.