A client-principal is a handle-based object that functions as the security token in an ABL application. As such, each instance of a client-principal object encapsulates a single user identity for an OpenEdge database connection, an ABL session, or an entire application. You can explicitly create a client-principal object that you initialize to authenticate a user identity, or you can obtain a copy of an existing client-principal object that represents the user identity already established for a given database connection or ABL session.
If you do not explicitly create a client-principal object for a database connection identity, OpenEdge implicitly creates one to represent the authenticated or default user identity for the connection. The ABL session identity is undefined unless you set the session identity using a client-principal object that you create or that you obtain from a database connection or other ABL session with an established identity.
You can thus use an instance of the object to assert user credentials to be authenticated as a user identity and to establish a user login session for the authenticated user identity. A user login session is a run-time construct that can be in any one of several states, indicated by the
LOGIN-STATE and
STATE-DETAIL attributes on the client-principal object handle (see
Table 12). These states are controlled by methods and other attribute settings on the client-principal object handle, in addition to other ABL elements that operate on the object, such as the
SET-DB-CLIENT function and
SET-CLIENT( ) method on the
SECURITY-POLICY system handle. Such states include whether the session is logged in or out, or has been suspended, expired, or otherwise failed. Thus, a client-principal object, provides the following application features:
Contains a variety of information about the user login session, such as the user ID and unique session ID, a description of the authentication system (domain), a description of the login environment, the state of the login session, a unique identifier for the session, and other information, some of which are optional, depending on how you use the client-principal object
Can be used to authenticate or validate a user identity against a trusted domain registry, and there by assign the identity to a particular OpenEdge context according to the type of domain registry (local database or session registry) and associated database option settings
With all of its features, the ultimate purpose of a client-principal object is to enable your application to authenticate a user identity once and set that same identity many times, in many different places, thus achieving the goal of single sign-on for all database connections and sessions in your ABL application.
