Exporting and importing a client-principal object

An important feature of the client-principal object is that it can be exported from one ABL session and imported to another using the EXPORT-PRINCIPAL( ) and IMPORT-PRINCIPAL( ) methods. This can be done before or after the user identity it represents has been authenticated and the object sealed.

Exporting an unsealed client-principal object, for example, allows an ABL client session to pass a user identity to an PAS for OpenEdge instance acting as an authentication service. The instance then imports the security token as its own client-principal object and after authenticating and sealing the object with a user authentication operation, it exports the sealed security token back to the ABL client to set the user identity for the session and database connections, as appropriate, using an SSO operation.

Exporting and importing a sealed client-principal allows an authenticated user identity to be passed from one ABL session to another in an multi-tier application, allowing multiple ABL sessions of one application to set the same user identity through SSO or to maintain a single application identity that is separate from the individual identities set for each session. In either case, the original user authenticating session typically initializes the SESSION-ID attribute with a unique value that identifies the sealed client-principal as representing the identity for the entire application. Depending on the session type of a PAS for OpenEdge instance, this also allows all ABL sessions in a single (virtual) application “session” to share data that is stored and keyed with this SESSION-ID value in a context database.

A useful source for the SESSION-ID attribute value is the ClientContextId property on the Progress.Lang.OERequestInfo class. The information encapsulated by this class is passed with any communication between a PAS for OpenEdge client and the instance. The object is accessible to the instance with a request from the client through the CURRENT-REQUEST-INFO attribute of the SESSION system handle. The object is also accessible to the client with a response from the instance in the RESPONSE-INFO attribute on the server object handle used to access the instance. Similarly, a client can set the ClientContextId property value by accessing the OERequestInfo object using the REQUEST-INFO attribute on the server object handle, and the instance can set a response using the CURRENT-RESPONSE-INFO attribute on its SESSION handle. By using the same unique value for the ClientContextId property an application-wide context can be maintained across many clients and instances, and the same value can be stored in the SESSION-ID attribute of an exported or imported client-principal object to keep track of the user identity for all these connected client and PAS for OpenEdge sessions. For examples and information about using the ClientContextId property to maintain a user login session across the several ABL sessions of a multi-tier application, see OpenEdge Programming Interfaces.