Previous Topic: Tunnel Service APINext Topic: DMS Workflow API


Event API

This section contains the following topics:

Event API Overview

Event API Setup

Event Provider Structures

Overview of Event Types

Event Function Declarations

Example of an Active Policy

Configuring the Policy Server for the Event Handler

Event API Overview

The SiteMinder Event API lets you create custom event handlers.

Through the Event API, SiteMinder can log events using outside sources, providers, or applications. You can then access the logged information through these other sources, providers, or applications.

Using the Event API, you can build applications to alert administrators of SiteMinder activity. For example, an event handler can send an e-mail to the administrator when the accounting server starts or someone creates a new policy.

Event API Setup

Each event handler is an instance of a shared library that supports the Event API provider interface. To support custom event handlers, you must build a shared library.

Install the shared library in one of the following locations:

The shared library must export the following entry points:

To build an event handler, include the SmEventApi.h header file:

#include "SmEventApi.h"

Event Provider Structures

The following table lists the structure definitions used with Event Provider API functions:

Structure

Description

SmLog_Access_t

Contains information about access events.

SmLog_EMS_t

Contains information about Entitlement Management Services (EMS) events. EMS events result from actions performed on directory objects.

SmLog_Obj_t

Contains information about object events.

SmLog_System_t

Contains information about system events.

SmLog_Access_t

Contains information about an access event.

Syntax
typedef struct SmLog_Access_s
{
   long nVersion;
   long nCurrentTime;
   Sm_Api_Reason_t nReason;
   char* szAgentName;
   char* szSessionId;
   char* szClientIp;
   char* szUserName;
   char* szDomainOid;
   char* szRealmName;
   char* szRealmOid;
   char* szAuthDirName;
   char* szAuthDirServer;
   char* szAuthDirNamespace;
   char* szServer;
   char* szResource;
   char* szAction;
   char* szTransactionId;
   char* szStatusMsg;
   char* szDomainName;
   char* szImpersonatorName;
   char* szImpersonatorDirName;
} SmLog_Access_t;

Field

Description

nVersion

Version number of the Policy Server.

nCurrentTime

Policy Server time (in GMT) when the event occurred.

nReason

Contains the reason identifier.

szAgentName

Name of the agent.

szSessionId

Session ID.

szClientIp

The IP address of the client.

szUserName

Full distinguished name of the user or administrator.

szDomainOid

The object identifier of the domain object.

szRealmName

Name of the realm in which the resource is protected.

szRealmOid

Object identifier for the realm object.

szAuthDirName

The name of the directory.

szAuthDirServer

Directory Server of a SiteMinder user directory where user’s context was established.

szAuthDirNamespace

Directory Namespace such as LDAP, WinNT, or ODBC.

szServer

Name of the server holding the resource.

szResource

Name of the resource.

szAction

Type of action performed on the resource. A typical action when accessing web resources is a GET.

szTransactionId

Identifier of a transaction between the agent and Policy Server. The agent sets this ID and the Policy Server logs it.

When the agent makes a request to the Policy Server, it associates an ID with the request. Since the agent may make many such requests, the agent uses the ID to match information from the Policy Server with the originating request.

szStatusMsg

Status message.

szImpersonatorName

Specifies the name of the impersonator.

Set to NULL if there is no impersonated session in progress.

szDomainName

Specifies the name of the domain.

szImpersonator
  DirName

Specifies the name of the user directory used to authenticate the impersonator.

Set to NULL if there is no impersonated session in progress.

More Information:

Sm_Api_Reason_t

SmLog_EMS_t

Contains information about an Entitlement Management Services (EMS) event. EMS events result from actions performed on directory objects.

Syntax

typedef struct SmLog_EMS_s
{
   long nVersion;
   long nCurrentTime;
   char* szUserName;
   char* szSessionId;
   char* szDirName;
   char* szObjName;
   char* szObjPath;
   char* szObjClass;
   char* szOrgName:
   char* szRoleName;
   int   szFieldDesc;
   char* szStatusMsg;
} SmLog_EMS_t;

Field

Description

nVersion

Version number of the Policy Server.

nCurrentTime

Policy Server time (in GMT) when the event occurred.

szUserName

If the user is an administrator, the ID of the administrator who initiated the EMS event. If the event is an end-user event, the user name is Registration.

szSessionID

EMS Service Session ID.

szDirName

Name of the SiteMinder directory affected by the EMS event.

szObjName

Name of the object targeted by this event.

szObjPath

Full distinguished name of the object.

szObjClass

Class name of the object.

szOrgName

Name of the object’s organization.

szRoleName

Name of the role to which the object is related (only for events that involve roles).

szFieldDesc

Description of the event.

szStatusMsg

The status message.

SmLog_Obj_t

Contains information about an object event.

Syntax

typedef struct SmLog_Obj_s
{
   long nVersion;
   long nCurrentTime;
   char* szUserName;
   char* szSessionId;
   char* szDomainOid;
   char* szObjName;
   char* szObjOid;
   char* szFieldDesc;
   char* szStatusMsg;
} SmLog_Obj_t;

Field

Description

nVersion

Version number of the Policy Server.

nCurrentTime

Policy Server time (in GMT) when the event occurred.

szUserName

The name of the user who triggered the event.

szSessionId

Session ID.

szDomainOid

Object identifier for the domain object.

szObjName

The name of the object.

szObjOid

Object identifier for the object.

szFieldDesc

User DN.

szStatusMsg

Status message.

SmLog_System_t

Contains information about a system event.

Syntax

typedef struct SmLog_System_s
{
   long nVersion;
   long nCurrentTime;
   char* szName;
   char* szIpAddress;
   int   nIpPort;
   char* szMsg;
} SmLog_System_t;

Field

Description

nVersion

Version number of the Policy Server.

nCurrentTime

Time when the event occurred.

szName

Name of the client, database, or directory.

szIpAddress

IP address of the client.

nIpPort

Port number that the client communicates on.

szMsg

Buffer to receive string message for an event.

Overview of Event Types

SiteMinder logs four types of events. All event classifications have well-defined data. The types of events are:

Access Event Type

Access events result from user-related activities. They are called in the context of authentication, authorization, administration, and affiliate activity.

There are four categories of access events. Each of these event categories responds with its own set of events. The following table lists the access event categories and their associated response events.

Event Category

SiteMinder Activity

SiteMinder Event

Authentication

  • User authentication accepted
  • User authentication rejected
  • User authentication attempted
  • User authentication challenged
  • User session
    validated

SmLogAccessEvent_AuthAccept

SmLogAccessEvent_AuthReject

SmLogAccessEvent_AuthAttempt

SmLogAccessEvent_AuthChallenge

SmLogAccessEvent_ValidateAccept

SmLogAccessEvent_ValidateReject

SmLogAccessEvent_AuthLogout

Authorization

  • User authorization accepted
  • User authorization rejected

SmLogAccessEvent_AzAccept

SmLogAccessEvent_AzReject

SmLogAccessEvent_AzUnresolved

Administration

  • Administrator login
  • Administrator rejected
  • Administrator logout

SmLogAccessEvent_AdminLogin

SmLogAccessEvent_AdminLogout

SmLogAccessEvent_AdminReject

Affiliate

SmLogAccessEvent_Visit

Filter Access Events

Beginning with SiteMinder v5.x, you can filter the kinds of access events you want to audit and log using the Auditing tab on the Policy Server Management Console. For example, for each of the four event categories you can select Log All Events or Log No Events.

In addition, for the Authentication, Authorization, and Administration categories, you can select Log Rejection Events Only. For example, if this option is selected for the Authentication category, SmLogAccessEvent_AuthReject events would be logged, but SmLogAccessEvent_AuthAccept events would not be. Also, note the following behavior when Log Rejection Events Only is selected:

EMS Event Type

EMS events result from actions performed on directory objects.

SiteMinder calls EMS events when:

After calling an event, SiteMinder logs session activities to the objects. When an EMS-based application, such as Delegated Management Services (DMS), logs in to EMS, a new session is created. EMS validates the login session and reports an appropriate event.

These Directory objects are associated with EMS events:

Each of the objects above is associated with the following object events:

EMS events are classified according to category:

Event Category

EMS Event

SmLogEmsCat_DirectoryAdmin

SmLogEmsEvent_CreateUser

SmLogEmsEvent_DeleteUser

SmLogEmsEvent_ModifyUser

SmLogEmsEvent_AssignUserRole

SmLogEmsEvent_RemoveUserRole

SmLogEmsEvent_EnableUser

SmLogEmsEvent_DisableUser

SmLogEmsEvent_CreateOrg

SmLogEmsEvent_DeleteOrg

SmLogEmsEvent_ModifyOrg

SmLogEmsEvent_CreateRole

SmLogEmsEvent_DeleteRole

SmLogEmsEvent_ModifyRole

SmLogEmsEvent_PasswordModify

SmLogEmsEvent_CreateObject

SmLogEmsEvent_DeleteObject

SmLogEmsEvent_ModifyObject

SmLogEmsCat_DirectoryUser

SmLogEmsEvent_CreateUser

SmLogEmsEvent_ModifyUser

SmLogEmsEvent_PasswordModify

SmLogEmsCat_DirectorySession

SmLogEmsEvent_Login

SmLogEmsEvent_Logout

SmLogEmsEvent_LoginFail

SmLogEmsEvent_SessionTimeout

SmLogEmsEvent_AuthFail

Logging Workflow Events

When a preprocess or postprocess event is handled, the event will be logged. In this case, the category in the log is either SmLogEmsCat_EventPreprocess or SmLogEmsCat_EventPostprocess. The Event ID is the original Event ID (for example, SmLogEmsEvent_CreateUser).

In addition, the following fields of SmLog_EMS_t apply to preprocess and postprocess events:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who generated the original event.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the target object is located.

szObjPath

Full distinguished name of the object targeted by this event.

szFieldDesc

Name of the workflow library that executed the event.

szStatusMsg

This includes a workflow completion code and an optional error message. The following workflow completion codes are defined in SmApi.h:

  • Sm_DmsWorkflowApi_Success
  • Sm_DmsWorkflowApi_Ignore
  • Sm_DmsWorkflowApi_Failure
  • Sm_DmsWorkflowApi_Reject
  • Sm_DmsWorkflowApi_NoUserContext
  • Sm_DmsWorkflowApi_SkipSuccess

More Information:

SmLog_EMS_t

Object Event Type

The SiteMinder environment contains elements, called objects, such as domains, policies, realms, and user directories. Collectively, these persistent objects form an object store.

SiteMinder calls object events when objects are created, updated, or deleted. The object events are:

The following SiteMinder objects are associated with object events:

Agents

Agent Groups

Agent Types

Agent Type Attributes

Agent Keys

Key Management

Domains

Administrators

Policies

Policy Links

Password Policies

Registration

User Policies

User Directories

Realms

Management Commands

Responses

Response Groups

Response Attributes

Certificate Mapping

Rules

Rule Groups

Authentication

Authentication and Authorization Mapping

Authentication schemes

ODBC Query

Root

Root Configuration

After calling an object event, SiteMinder logs session activities to the objects. When an application logs in to the object store, a new session is created. SiteMinder validates the login session and reports an appropriate event.

Authentication Events

Authentication reports the following events:

Management Command Events

The management commands are not persistent. They log information about management functions, such as flushing cache and changing keys. Management commands are associated with the following events:

System Event Type

System events indicate system- and server-related activities. The following table lists the system events:

Activity Type

SiteMinder Event

Server activity

SmLogSystemEvent_ServerInit

SmLogSystemEvent_ServerInitFail

SmLogSystemEvent_ServerUp

SmLogSystemEvent_ServerDown

SmLogSystemEvent_LogFileOpenFail

SmLogSystemEvent_ServerHeartBeat

System activity

SmLogSystemEvent_AgentInfo

SmLogSystemEvent_AgentConnectionStart

SmLogSystemEvent_AgentConnectionFail

SmLogSystemEvent_AgentConnectionEnd

SmLogSystemEvent_DbConnect

SmLogSystemEvent_DbConnectFail

SmLogSystemEvent_LdapConnect

SmLogSystemEvent_LdapConnectFail

SmLogSystemEvent_AmbiguousResourceMatch

SmLogSystemEvent_AmbiguousRADIUSMatch

SmSystemEvent_AgentHeartBeat

SmLogAccessEvent_AuthAccept

This event is called when the user is authenticated.

The following table lists the sssociated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szSessionId

Contains the session identifier of the user being authenticated.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szAuthDirName

Contains the name of the directory against which the user was authenticated.

szAuthDirServer

Contains the authentication directory data source.

szAuthDirNamespace

Contains the namespace of the authentication directory.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

szTransactionId

Contains information about the newly created session in the following format:
idletime=N;maxtime=N;authlevel=N

In the format example:

  • idletime is the idle timeout in seconds of the newly created session
  • maxtime is the maximum timeout in seconds of the newly created session
  • authlevel is the security level of the newly created session

SmLogAccessEvent_AuthReject

This event is called when the user is not authenticated.

The following table lists the sssociated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szAuthDirName

Contains the name of the directory against which the user was authenticated.

szAuthDirServer

Contains the authentication directory data source.

szAuthDirNamespace

Contains the namespace of the authentication directory.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

SmLogAccessEvent_AuthAttempt

This event is called when the authentication attempt has failed.

The following table lists the associated SmLog_Access_t fields

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

SmLogAccessEvent_AuthChallenge

This event is called when authentication is challenged.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

SmLogAccessEvent_AzAccept

This event is called when the user is authorized to access the resource.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szSessionId

Contains the session identifier of the user whose authorization is accepted.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

szTransactionId

Contains the transaction identifier, which is set by the agent to track information returned from the Policy Server. The Policy Server logs this ID.

SmLogAccessEvent_AzReject

This event is called when the user is not authorized to access the resource.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szAgentName

Name of the agent.

szSessionId

Contains the session identifier of the user whose authorization is rejected.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the user.

SzDomainOid

Contains the object identifier of the domain under which the resource was accessed.

szRealmName

Contains the name of the realm being accessed.

szRealmOid

Contains the object identifier of the realm.

szResource

Contains the name of the resource that the user is accessing.

szAction

Contains the action associated with the resource.

SmLogAccessEvent_AdminLogin

This event is called when an administrator login is successful.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szSessionId

Contains the session identifier of the administrator whose login is successful.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the administrator.

SmLogAccessEvent_AdminLogout

This event is called when an administrator logs out.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szSessionId

Contains the session identifier of the administrator who logged out.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the administrator.

SmLogAccessEvent_AdminReject

This event is called when an administrator login is rejected.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

nReason

Contains the reason identifier.

szClientIp

Contains the IP address of the agent.

szUserName

Name of the administrator.

szStatusMsg

Contains the reason for the login reject.

SmLogAccessEvent_AuthLogout

This event is called when the authentication server logs out a session.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

nReason

The reason identifier, of type Sm_Api_Reason_t. .

SmLogAccessEvent_ValidateAccept

This event is called when a session validation is successful.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

 

SmLogAccessEvent_ValidateReject

This event is called when a session validation is rejected.

The following table lists the associated SmLog_Access_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

 

SmLogEmsEvent_CreateUser, SmLogEmsEvent_DeleteUser, SmLogEmsEvent_ModifyUser

Creating, deleting, or modifying a user object results in an EMS event. User objects are LDAP entities of the class inetorgperson or entities of a class that extends inetorgperson.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

If this is an administrative event, the name of the administrator who is creating, modifying, or deleting the user object. If this is an end-user event, the user name is Registration.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the user is located.

szObjName

The name (user ID) of the user object targeted by this event.

szObjPath

Full distinguished name of the user object targeted by this event.

szObjClass

Class name of the user object.

szOrgName

Name of the user object’s organization.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_PasswordModify

Changing a user password results in an EMS event.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

If this is an Administrative event, the name of the administrator who is modifying the password. If this is an end-user event, the user name is Registration.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the user is located.

szObjName

The name (user ID) of the user object targeted by this event.

szObjPath

Full distinguished name of the user object targeted by this event.

szObjClass

Class name of the user object.

szOrgName

Name of the user object’s organization.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_AssignUserRole, SmLogEmsEvent_RemoveUserRole

Assigning a user to a role or removing a user from a role results in an EMS event. Roles are LDAP entities of the class groupofuniquenames or entities that extend groupofuniquenames.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is assigning or removing the role.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the role is located.

szObjName

The name (user ID) of the user object targeted by this event.

szObjPath

Full distinguished name of the user object targeted by this event.

szObjClass

Class name of the user object.

szOrgName

Name of the user’s organization.

szRoleName

Name of the role that is being assigned or removed.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_EnableUser, SmLogEmsEvent_DisableUser

These events are called when a user’s access rights are enabled or disabled. Access rights pertain to the user’s ability to get resources that are under SiteMinder protection.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is enabling or disabling the user’s access rights.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the user is located.

szObjName

The name (user ID) of the user object targeted by this event.

szObjPath

Full distinguished name of the user object targeted by this event.

szObjClass

Class name of the user object.

szOrgName

Name of the user’s organization.

szFieldDesc

Description of the event.

szStatusMsg

Status message. This will be 0 if the user’s access rights are enabled, and non-zero if the user’s access rights are disabled.

SmLogEmsEvent_CreateOrg, SmLogEmsEvent_DeleteOrg, SmLogEmsEvent_ModifyOrg

These events are called when an organization object is created, deleted, or modified. Organization objects are LDAP entities of the class organizationalunit or entities of a class that extends organizationalunit.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is creating, modifying, or deleting the organization.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the organization is located.

szObjName

The name (user ID) of the organization object targeted by this event.

szObjPath

Full distinguished name of the organization object targeted by this event.

szObjClass

Class name of the organization object.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_CreateRole, SmLogEmsEvent_DeleteRole, SmLogEmsEvent_ModifyRole

These events are called when a role object is created, deleted, or modified. Role objects are LDAP entities of the class groupofuniquenames or entities of a class that extends groupofuniquenames.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is creating, modifying, or deleting the group.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the group is located.

szObjName

The name of the group targeted by this event.

szObjPath

Full distinguished name of the group object targeted by this event.

szObjClass

Class name of the group object.

szOrgName

Name of the user group’s organization.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_CreateObject, SmLogEmsEvent_DeleteObject, SmLogEmsEvent_ModifyObject

These events are called when an LDAP entry with an object class of top is created, deleted, or modified. The top object class is a superclass for all other object classes in an LDAP directory. These events apply to any LDAP entry that uses the attribute objectclass.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is creating, modifying, or deleting the object.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the object is located.

szObjName

The name of the object targeted by this event.

szObjPath

Full distinguished name of the object targeted by this event.

szObjClass

Class name of the object.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_Login, SmLogEmsEvent_Logout

These events are called when an administrator logs in or logs out.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator.

szSessionId

The EMS session ID.

szDirName

The name of the SiteMinder directory where the administrator is located.

szObjName

The name (UID) of the administrator.

szObjPath

Full distinguished name of the administrator.

szOrgName

Name of the user administrator’s organization.

szFieldDesc

Description of the event.

szStatusMsg

Status message. Used only if the event was not handled successfully.

SmLogEmsEvent_AuthFail

This event is called when an administration authentication fails.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator.

szSessionId

The EMS session ID. This will probably not exist.

szFieldDesc

Description of the event.

szStatusMsg

Status message.

SmLogEmsEvent_SessionTimeout

This event is called when an EMS server session times out.

The following table lists the associated SmLog_Ems_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator.

szSessionId

The EMS session ID.

szOrgName

Name of the administrator’s organization

szFieldDesc

Description of the event.

szStatusMsg

Status message.

 

SmLogObjEvent_Create

This event is called when system or domain objects are created.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is creating the object.

szSessionId

The session ID of the administrator who is creating the object.

szDomainOid

If the object being created is a domain object, this value is set to the domain object identifier.

szObjName

Name of the object being created.

szObjOid

Object identifier of the object being created.

SmLogObjEvent_Update

This event is called when system or domain objects are updated.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is updating the object.

szSessionId

The session ID of the administrator who is updating the object.

szDomainOid

If the object being created is a domain object, this value is set to the domain object identifier under which the object is updated.

szObjName

Name of the object being updated.

szObjOid

Object identifier of the object being updated.

szFieldDesc

Administrator’s DN.

SmLogObjEvent_Delete

This event is called when system or domain objects are deleted.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is deleting the object.

szSessionId

The session ID of the administrator who is deleting the object.

szDomainOid

If the object being created is a domain object, this value is set to the domain object identifier under which the object is deleted.

szObjName

Name of the object being deleted.

szObjOid

Object identifier of the object being deleted.

SmLogObjEvent_Login

This event is called when an administrator or an application (such as smobjimport) logs into the policy store.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator or application logging into the policy store.

szSessionId

The session ID of the administrator or application logging into the policy store.

SmLogObjEvent_FailedLoginAttemptsCount

This event is called when a user login fails and there is a password policy that applies.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The user whose login attempt failed.

szSessionId

The session ID of the user.

szObjName

Name of directory where the user was found.

szFieldDesc

User’s DN.

szStatusMsg

Number of times that the login was attempted. This number cannot be higher than the number of attempts that results in a disabled account.

SmLogObjEvent_Logout

This event is called when an administrator or an application (such as smobjimport) logs out of the policy store.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator or application logging out of the policy store.

szSessionId

The session ID of the administrator or application logging out of the policy store.

SmLogObjEvent_LoginReject

This event is called when an administrator or an application login to the policy store is rejected.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator or application that was rejected.

SmLogObjEvent_FlushAll

This event is called when all the SiteMinder caches are flushed, including user sessions, resource information, and user directory caches.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is flushing the cache.

szSessionId

The session ID of the administrator who is flushing the cache.

SmLogObjEvent_FlushUser

This event is called when a user is flushed from user session cache.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is flushing the user.

szSessionId

The session ID of the administrator who is flushing the user.

szObjName

Name of the directory where the user is defined.

szObjOid

Object identifier of the directory where the user is defined.

szFieldDesc

DN of the user being flushed.

SmLogObjEvent_FlushUsers

This event is called when all users are flushed from user session cache.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is flushing the users.

szSessionId

The session ID of the administrator who is flushing the users.

SmLogObjEvent_FlushRealms

This event is called when all the realms are flushed from resource information cache.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is flushing the realms.

szSessionId

The session ID of the administrator who is flushing the realms.

SmLogObjEvent_ChangeDynamicKeys

This event is called when the dynamic key is changed.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is changing the keys.

szSessionId

The session ID of the administrator who is changing the keys.

SmLogObjEvent_ChangePersistentKey

This event is called when the persistent key is changed.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is changing the keys.

szSessionId

The session ID of the administrator who is changing the keys.

SmLogObjEvent_ChangeSessionKey

This event is called when the session key is changed.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

 

SmLogObjEvent_ChangeUserPassword

This event is called whenever an administrator changes a user’s password.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is changing the password.

szSessionId

The session ID of the administrator who is changing the password.

szObjName

Name of the directory where the user is defined.

szObjOid

Object identifier of the directory where the user is defined.

szFieldDesc

DN of the user whose password is being changed.

SmLogObjEvent_CreateUserSuccess

This event is called when a new user is created.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is creating the user account.

szSessionId

The session ID of the administrator who is creating the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account is being created.

 

SmLogObjEvent_DeleteUserSuccess

This event is called when a user account is deleted in the directory.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is deleting the user account.

szSessionId

The session ID of the administrator who is deleting the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account is being deleted.

 

SmLogObjEvent_ChangeDisabledUserState

This event is called under the following conditions:

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is changing the state of the account.

szSessionId

The session ID of the administrator who is changing the state of the account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account is being changed.

szStatusMsg

Reason for changing the state of the account.

 

SmLogObjEvent_ModifyUserSuccess

This event is called when a user account is modified.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is modifying the user account.

szSessionId

The session ID of the administrator who is modifying the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account is being modified.

 

SmLogObjEvent_CreateUserFail

This event is called when the user account cannot be created.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is attempting to create the user account.

szSessionId

The session ID of the administrator who is attempting to create the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account could not be created.

SmLogObjEvent_DeleteUserFail

This event is called when the user account cannot be deleted.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is attempting to delete the user account.

szSessionId

The session ID of the administrator who is attempting to delete the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account could not be deleted.

 

SmLogObjEvent_ModifyUserFail

This event is called when the user account cannot be modified.

The following table lists the associated SmLog_Obj_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szUserName

The name of the administrator who is attempting to modify the user account.

szSessionId

The session ID of the administrator who is attempting to modify the user account.

szObjName

Name of the directory where the user is defined.

szFieldDesc

DN of the user whose account could not be modified.

 

SmLogSystemEvent_ServerInit

The server is initializing.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the server.

szMsg

Information about the server in the following format:

Product=%,Platform=%,Version=%,Update=%,
    Label=%,Crypto=%,UTC=%,TZ=%

In the format example:

Product is the name of the server.

Platform is the supported platform of the server software.

Version is the version number of the SiteMinder server software.

Update is the update number of the server software.

Label is the build number of the server software.

Crypto is the crypto strength.

UTC is the time in the Universal Time Format.

TZ is the time zone.

Unknown clauses are left blank.

Example:

Product=smservacct,Platform=Windows NT,
    Version=4.0,Update=None,Label=C144,
    Crypto=56,UTC=949621705,TZ=5

SmLogSystemEvent_ServerInitFail

Called by the event handler to find out which server initialization failed according to the system category in the event call.

This event has no associated SmLog_System_t fields.

SmLogSystemEvent_ServerUp

Called by the event handler to find out which server is up and running according to the system category in the event call.

This event has no associated SmLog_System_t fields.

SmLogSystemEvent_ServerDown

Called by the event handler to find out which server is down according to the system category in the event call.

This event has not associated SmLog_System_t fields.

SmLogSystemEvent_LogFileOpenFail

This event is called when the text file used for audit logging could not be opened.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szMsg

The name of the audit log file that could not be opened.

SmLogSystemEvent_ServerHeartbeat

This event provides periodic information about the server. It is called every 30 seconds.

The following table lists associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the server.

szIpAddress

Name of the host where the server is running.

nIpPort

Port on which the server is listening.

SmLogSystemEvent_AgentInfo

Contains information about the agent.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the agent.

szMsg

Information about the agent in the following format:

Product=%,Platform=%,Version=%,Update=%,
    Label=%,Crypto=%,UTC=%,TZ=%

In the format example:

Product is the name of the agent software.

Platform is the supported platform of the agent software.

Version is the version number of the agent software.

Update is the update number of the agent software.

Label is the build number of the agent software.

Crypto is the crypto strength.

UTC is the time in the Universal Time Format.

TZ is the time zone.

Unknown clauses are left blank.

For example, the Web Agent issues the following:

Product=WebAgent,Platform=NT/ISAPI,
    Version=4.0,Update=SP1,Label=C134,
    Crypto=56,UTC=949621705,TZ=5

SmLogSystemEvent_AgentConnectionStart

This event is called when the agent connects to the Policy Server.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the agent.

szIpAddress

The IP Address of the agent machine.

nIpPort

Port on the Policy Server machine that the agent is connected to.

SmLogSystemEvent_AgentConnectionFail

This event is called when the agent connection fails.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the agent.

szIpAddress

The IP Address of the agent machine.

nIpPort

Port on the Policy Server machine that the agent tried to connect to.

SmLogSystemEvent_AgentConnectionEnd

This event is called when the agent connection ends.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the agent.

szIpAddress

The IP Address of the agent machine.

nIpPort

Port on the Policy Server machine that the agent was connected to.

SmLogSystemEvent_DbConnect

This event is called when the Policy Server connects to the database.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

The name of the data source.

 

SmLogSystemEvent_DbConnectFail

This event is called when the Policy Server connection to the database fails.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

The name of the data source.

szMsg

The error message.

 

SmLogSystemEvent_LdapConnect

This event is called when the Policy Server connects to an LDAP directory.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

The name of the LDAP directory.

szIpAddress

The IP Address of the LDAP directory.

nIpPort

Port of the LDAP directory.

SmLogSystemEvent_LdapConnectFail

This event is called when the Policy Server connection to the LDAP directory fails.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

The name of the LDAP directory.

szIpAddress

The IP Address of the LDAP directory.

nIpPort

Port of the LDAP directory.

szMsg

The error message.

 

SmLogSystemEvent_AmbiguousResourceMatch

This event is called when there is an ambiguous resource match.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the machine requesting the resource.

szMsg

The resource requested.

SmLogSystemEvent_AmbiguousRadiusMatch

This event is called when there is an ambiguous RADIUS match.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

The name of the RADIUS device.

SmLogSystemEvent_AgentHeartbeat

This event is called whenever an agent makes a DoManagement request.

The following table lists the associated SmLog_System_t fields:

Field

Description

nVersion

Version number of the SiteMinder server.

nCurrentTime

Time when the event occurred.

szName

Name of the agent.

szIpAddress

IP address of the agent.

nIpPort

Port on the Policy Server machine to which the agent is connected.

Event Function Declarations

The table below lists the functions used in the Event API. Your shared library must export these entry points.

Function Definition

Description

SmEventInit()

Called by the Policy Server so that an event handler can perform its own initialization procedure.

SmEventRecord()

Called by the Policy Server when an event has been signalled.

SmEventRelease()

Called by the Policy Server so that an event handler can perform its own rundown procedure.

SmEventInit()

The Policy Server calls this function to let an event provider perform its own initialization procedure. The call is made once when the provider is first loaded.

Syntax

int SM_EXTERN SmEventInit();

Returns

Returns 1 if successful or 0 if unsuccessful.

SmEventRecord()

The Policy Server calls this function when an event has been signalled.

Syntax

void SM_EXTERN SmEventRecord (
   const int   nCategoryType,
   const int   nCategory,
   const int   nEventId,
   void*       pData
);

Parameter

I/O

Description

nCategoryType

I

The type of the event being logged. One of the following valid values:

  • SmLog_Access
  • SmLog_EMS
  • SmLog_Obj
  • SmLog_System

nCategory

I

The event category. A list of valid event categories follows this parameter table.

nEventID

I

The event.

pData

I

The pointer to the property instance. The structure could be one of the following:

Valid values for the nCategory parameter are as follows:

SmLogAccessCat_Admin

SmLogAccessCat_Affiliate

SmLogAccessCat_Auth

SmLogAccessCat_Az

SmLogEmsCat_DirectoryAdmin

SmLogEmsCat_DirectorySession

SmLogEmsCat_DirectoryUser

SmLogEmsCat_EventPostprocess

SmLogEmsCat_EventPreprocess

SmLogObjCat_ActiveExpr

SmLogObjCat_Admin

SmLogObjCat_Agent

SmLogObjCat_AgentGroup

SmLogObjCat_AgentKey

SmLogObjCat_Auth

SmLogObjCat_AuthAzMap

SmLogObjCat_CertMap

SmLogObjCat_Domain

SmLogObjCat_KeyManagement

SmLogObjCat_ManagementCommand

SmLogObjCat_ODBCQuery

SmLogObjCat_PasswordPolicy

SmLogObjCat_Policy

SmLogObjCat_PolicyLink

SmLogObjCat_Property

SmLogObjCat_PropertyCollection

SmLogObjCat_PropertySection

SmLogObjCat_Realm

SmLogObjCat_Response

SmLogObjCat_ResponseAttr

SmLogObjCat_ResponseGroup

SmLogObjCat_Root

SmLogObjCat_RootConfig

SmLogObjCat_Rule

SmLogObjCat_RuleGroup

SmLogObjCat_Scheme

SmLogObjCat_SelfReg

SmLogObjCat_TaggedString

SmLogObjCat_UserDirectory

SmLogObjCat_UserPolicy

SmLogObjCat_Variable

SmLogObjCat_VariableType

SmLogObjCat_Vendor

SmLogObjCat_VendorAttr

SmLogSystemCat_Acct

SmLogSystemCat_Admin

SmLogSystemCat_Auth

SmLogSystemCat_Az

SmLogSystemCat_Combined

SmLogSystemCat_System

SmEventRelease()

The Policy Server calls this function to let the event handler perform its own rundown procedure. This call is made once when SiteMinder is shutting down.

Syntax

void SM_EXTERN SmEventRelease();

Example of an Active Policy

This function returns true if the user belongs to the organizational unit specified in the parameter (param) field of the active policy expression.

<@ lib="SmAzAPI" func="activePolicy" param="Accounting" @>
*************************************************************
int SM_EXTERN activePolicy(
const Sm_Api_Context_t* lpApiContext,   
// the structure that provides API context
const Sm_Api_UserContext_t*  lpUserContext,  
// the structure that provides user context
const Sm_Api_RequestContext_t*  lpReqContext,   
// the structure that provides request context
const char* lpszParam,      
// the parameter string (null-terminated)
const int nBytesOutBuf,   
// the maximum size of the output buffer
char*  lpszOutBuf,     
// the output buffer to hold the null-terminated attribute value
const int  nBytesErrBuf,   
// the maximum size of the error message buffer
char* lpszErrBuf)     
// the output buffer to hold the null-terminated error message
{
/* User Context is required to use the functions like fGetProp, fSetProp.. */
if(!lpUserContext->bIsUserContext) {
   strncpy (lpszErrBuf, "No User Context ", nBytesErrBuf);
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
/* Buffer to store all the organizational units user belongs to. */
char lpszOrgUnit[30];
memset(lpszOrgUnit, 0, sizeof(lpszOrgUnit));
/*
// Check to see if an organizational unit has been 
// entered in the parameter.
*/
if(lpszParam == NULL || strlen(lpszParam) == 0) 
   {
   strncpy (lpszErrBuf, "Organizational unit is not entered ",
            nBytesErrBuf);
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
/* Get all the organizational units to which the user belongs. */
   int getResult = lpUserContext->fGetProp (
   lpUserContext->lpParam,
   "ou",         /* Attribute name */
   sizeof (lpszOrgUnit),lpszOrgUnit);
if (getResult < 0) 
   {
   strncpy (lpszErrBuf, 
       "Failed to get user password from user's profile attribute ",
       nBytesErrBuf);
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
    else
    {
   /* Check if the user belongs to the organization unit that is
   requested. */
   if(strstr(lpszOrgUnit, lpszParam) != NULL)
      {
/*
   // Yes the user belongs to the organization unit
   // mentioned in the parameter field of active policy.
*/
      strncpy(lpszOutBuf, "true", nBytesOutBuf);
      lpszOutBuf[nBytesOutBuf-1] = '\0';
      return strlen(lpszOutBuf);
      }
      else
      {
      strncpy (lpszErrBuf, 
         "The user does not belong to the requested organizational unit ", 
         nBytesErrBuf);
      lpszErrBuf[nBytesErrBuf-1] = '\0';
      return -1;
      }
   }
    /* everything failed.... */
    return 0;
}

Configuring the Policy Server for the Event Handler

You can add additional event handler libraries to the CA SiteMinder® Policy Server.

Note: If you do not have write access to the CA SiteMinder® binary files (XPS.dll, libXPS.so, libXPS.sl), an Administrator must grant you permission to use the related XPS command line tools using the Administrative UI or the XPSSecurity tool.

To add event handler libraries

  1. Open a command line on the Policy Server, and enter the following command:
    xpsconfig
    

    The tool starts and displays the name of the log file for this session, and a menu of choices opens.

  2. Enter the following:
    xps
    

    A list of options appears.

  3. Enter the following:
    5 (AuditSMHandlers)
    

    The settings for the event handler libraries appear.

  4. Type C, and then enter the path and file name of the event handler library you want to add. Separate multiple library locations with commas.

    The settings for the event handler libraries appear. The value you added is shown at the bottom of the settings as a "pending value."

  5. Do the following:
    1. Enter Q twice.
    2. Enter L.
    3. Enter Q to end your XPS session.

    Your changes are saved and the command prompt appears.