This section contains the following topics:
Configuring the Policy Server for the Event Handler
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.
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"
The following table lists the structure definitions used with Event Provider API functions:
Structure |
Description |
---|---|
Contains information about access events. |
|
Contains information about Entitlement Management Services (EMS) events. EMS events result from actions performed on directory objects. |
|
Contains information about object events. |
|
Contains information about system events. |
Contains information about an access event.
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 |
Specifies the name of the user directory used to authenticate the impersonator. Set to NULL if there is no impersonated session in progress. |
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. |
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. |
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. |
SiteMinder logs four types of events. All event classifications have well-defined data. The types of events are:
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 |
|
SmLogAccessEvent_AuthAccept SmLogAccessEvent_AuthReject SmLogAccessEvent_AuthAttempt SmLogAccessEvent_AuthChallenge SmLogAccessEvent_ValidateAccept SmLogAccessEvent_ValidateReject SmLogAccessEvent_AuthLogout |
Authorization |
|
SmLogAccessEvent_AzAccept SmLogAccessEvent_AzReject SmLogAccessEvent_AzUnresolved |
Administration |
|
SmLogAccessEvent_AdminLogin SmLogAccessEvent_AdminLogout SmLogAccessEvent_AdminReject |
Affiliate |
— |
SmLogAccessEvent_Visit |
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:
A login attempt that does not result in an accepted authentication is considered a failure. However, because the authentication was not actually rejected, events are not logged if Log Rejection Events Only is selected.
You can use SmLogAccessEvent_AuthAttempt events for intrusion detection.
A challenge is not considered a failure. It simply indicates a need for additional authentication information. However, because a challenge involves a rejected authentication, events are logged if Log Rejection Events Only is selected.
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 |
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:
|
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 reports the following 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 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 |
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: In the format example:
|
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. . |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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=%, 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, |
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.
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.
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.
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. |
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. |
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=%, 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, |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
The table below lists the functions used in the Event API. Your shared library must export these entry points.
Function Definition |
Description |
---|---|
Called by the Policy Server so that an event handler can perform its own initialization procedure. |
|
Called by the Policy Server when an event has been signalled. |
|
Called by the Policy Server so that an event handler can perform its own rundown procedure. |
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.
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:
|
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 |
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();
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; }
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
xpsconfig
The tool starts and displays the name of the log file for this session, and a menu of choices opens.
xps
A list of options appears.
5 (AuditSMHandlers)
The settings for the event handler libraries appear.
The settings for the event handler libraries appear. The value you added is shown at the bottom of the settings as a "pending value."
Your changes are saved and the command prompt appears.
Copyright © 2013 CA.
All rights reserved.
|
|