After the identity for a new or existing database connection is established, you can return a copy of the client-principal object associated with the connection identity by invoking the GET-DB-CLIENT function on the connection. This is especially useful to return a client-principal implicitly created by OpenEdge for the -U/-P connection parameters or the SETUSERID function so you can use it in an SSO operation to set the identity of another database connection or the current ABL session. You can similarly return a copy of the client-principal object used to set the current ABL session identity using the GET-CLIENT( ) method on the SECURITY-POLICY system handle.

Note that a given ABL session can create and maintain multiple client-principal objects for multiple user identities. However, for a given application, whether it is self-service, client-server, or multi-tier, a given application session typically maintains only one client-principal object per user.

Note: Progress Software recommends that any ABL session maintain only one client-principal object per user identity for all ABL sessions and database connections of an application. A context server might maintain a context store that includes a copy of this client-principal for each user of a multi-tier application, in addition to the user's application state and data. However, when creating or returning application context, this context server typically does so for only one user per request.

Note that all operations that seal a client principal, except the SETUSERID function, also start an associated user login session whose state is indicated by the value of the LOGIN-STATE attribute (see the table Client-principal object attributes are read-onlyTable 2). This login session is most useful for multi-tier applications that use the client-principal to pass an audit identity among several ABL sessions. In any case, the transition to different login states generates auditable events that can be recorded in each database connected in a session with the same audit identity.