Starting and maintaining user login sessions

A client (user) login session begins at the point that a client-principal object that represents a user identity is sealed in the LOGIN state after a successful user authentication (except using the SETUSERID function; see SETUSERIDfunction). If auditing is enabled, and the authenticated identity is an auditing identity, this also generates a login audit event that is recorded in each connected OpenEdge database according to its audit policy settings. The login audit event thus records the start of the login session, which continues with all activity associated with the same login session identity up to the point of any event that terminates the login session in any ABL session (for multi-tier) of the application. The terminating event for a login session can include:

An expired audit event — Generated at the point a client-principal that represents the login session is used when the current date and time exceeds the expiration time stamp set for the client-principal using the LOGIN-EXPIRATION-TIMESTAMP attribute on the client-principal.

You can start and manage user login sessions in a similar manner for any type of identity that you create. The following procedure applies generally in all cases.

To start and maintain a user login session:

1. Successfully authenticate a user identity using any ABL mechanism other than the SETUSERID function. For more information, see Authenticating and setting user identity. For examples, see:

Whether OpenEdge seals the client-principal or your application seals the client-principal, at that point, it also sets the read-only SEAL-TIMESTAMP attribute (see Table 12), which records the effective user authentication time for the user login session.

2. Given that the login is successful, whether created by OpenEdge or your applications, you can then use the sealed client-principal object in an SSO operation to assert and validate the user identity for the user login session against any OpenEdge database connection or ABL session.

3. If you need to transport the user login session between the ABL sessions of a multi-tier application, you can export the client-principal object in one ABL session context using the EXPORT-PRINCIPAL( ) method and import it into another session context using the IMPORT-PRINCIPAL( ) method on a different client-principal object, validating the result, if necessary, using the VALIDATE-SEAL( ) method on the newly imported client-principal object (see Table 13). For more information on when you might need to do this, see Establishing and managing identity for multi-tier applications.

4. To invalidate a user login session at any time or to ensure that it terminates in an unusable state, you can call the LOGOUT( ) method on the client-principal object handle (see Table 13). This effectively clears and resets the user identity maintained by this client-principal object to blank, and the client-principal object becomes unusable. OpenEdge does not automatically logout or otherwise terminate a user login session, unless you set the LOGIN-EXPIRATION-TIMESTAMP attribute on the client-principal object handle (see Table 11), before you seal the client-principal object.

Note: After you no longer need a client-principal object, be sure to delete it using the DELETE OBJECT statement, or you can re-initialize it using the INITIALIZE( ) method to authenticate a different user identity. For more information, see Initializing a client-principal for user authentication andSSO.

At any time during initialization and management of a user login session you can query the client-principal object attributes directly (see Table 11 and Table 12) and any properties you have defined using the GET-PROPERTY( ) method (see Table 13). Attributes you might want to query in any user login session include the read-only LOGIN-STATE and STATE-DETAIL attributes, which reflect changes in the login session state and the usability of the associated client-principal object.