Generating client login session context

Client login session context information consists of a client session ID that is recorded for each audit event generated during a client login session. Optionally, it also includes a record keyed by this client session ID that describes the authentication information for the client login session. OpenEdge supports two types of authentication systems for authenticating a user:

An ABL application-managed (external) authentication system that can optionally have a corresponding authentication domain defined for it in a trusted domain registry, either configured in an OpenEdge RDBMS or built at run time by the application itself. While not required to log in a client login session, this trusted domain registry is used to set user identities using the SET-CLIENT( ) method or the SET-DB-CLIENT built-in function.

OpenEdge allows you to use both types of authentication system to authenticate a user ID (auditing ID) that is recorded with all audit event records generated for the specified user ID, and which can also be used to indicate the application user ID at the time the event is recorded. For more information on how to specify a user identity as the auditing identity, see Setting up application security for auditing.

If you want additional information about the client login session recorded for the auditing context, in the Data Administration tool or Data Dictionary (character mode only), select the Record Authenticated Client Sessions option in the Database Options dialog box. For more information, see the Data Administration online help or OpenEdge Development: Basic Database Tools. Setting this option allows a client login session record (_client-session) to be written to the database that describes information about the authentication domain for the user ID represented by the client-principal object, various session security values (such as the database unique identifier), and additional detail from selected client-principal object attributes. When auditing is also enabled, this record becomes part of the auditing context.

The initiation and management of the client login session context is primarily the responsibility of methods on the client-principal object, which log in and manage a client login session. Without a client-principal object (using the SETUSERID function or User ID (-U)/Password (-P) parameters), OpenEdge records the configured auditing ID in all related audit event records, but creates no auditing client login session (client login session for the auditing ID). However, when you use a client-principal object to manage an auditing client login session, OpenEdge generates audit events to track the session, such as login, logout, and even the failure to log in (if so directed). Logging in with a client-principal object also causes the value of its SESSION-ID attribute to be written to every audit event record related to this auditing client login session. Again, the associated auditing ID (USER-ID attribute on the associated client-principal object) is written to all audit event records while the auditing client login session is active (logged in) and the auditing ID is also set as the client login session user ID.

OpenEdge supports several ABL elements that provide user identity and client session context information for the audit trail. The client-principal object provides most of the client login session context information. The following table shows ABL elements, listed in general order of usage, that generate auditing events or otherwise provide information for an auditing client login session context.

Table 33. ABL elements for auditing client login session context
ABL element	Description
SESSION-ID	Client-principal object attribute that specifies the client login session ID used to identify the client login session context in the audit trail. This value also keys any _client-session record created for the login session.
AUDIT-EVENT-CONTEXT	Client-principal object attribute that allows you to provide additional information to the audit event record's _Event-context field, which you can use to later to query audit event records. This value is written to audit event records generated for the AUTHENTICATION-FAILED( ), SEAL( ), and LOGOUT( ) methods.
AUTHENTICATION-FAILED( )	Client-principal object method that generates an audit event for a failed user login.
SEAL( )	Client-principal object method that generates an audit event for a successful user login, and also generates an optional client login session record with additional information.
SET-CLIENT( )	SECURITY-POLICY system handle method that sets the default OpenEdge session ID (which can be the auditing ID) using a client-principal object instance. It also asserts database connect IDs similar to the SET-DB-CLIENT function.
SET-DB-CLIENT	ABL function that asserts a user ID as the database connection ID (which can be the auditing ID) using a client-principal object instance. This function also generates an audit event for asserting the connection ID for a particular database.
LOGOUT( )	Client-principal object method that generates an audit event for user logout. It also logs out the client login session and sets the client-principal's LOGIN-STATE attribute to "LOGOUT" so that it cannot be validated to set an OpenEdge session or database connection ID.

If the option to record authenticated client sessions is set for an audit-enabled database, calling the SEAL( ) method on an associated client-principal object both logs in the auditing client session (generating an audit event record) and writes a _client-session record. In addition, OpenEdge relates every audit event record generated while this client login session user ID is set as the current auditing ID (including the login audit event record) to this _client-session record by the value of the SESSION-ID attribute on the client-principal object.

So, all audit event records generated, while the user ID for a given client login session is set as the current auditing ID, share the same session ID value and user ID value (which is also the configured auditing ID), and they also share these values with any _client-session record (related by the session ID value) that happens to be written for the given auditing client login session context.