Try OpenEdge Now
skip to main content
Programming Interfaces
Data Management : Application Security : Authenticating and managing user identity in ABL : Client-principal objects
Client-principal objects
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:
*Maintains a run-time user login session that can be optionally recorded in an OpenEdge RDBMS and also as part of an audit trail if auditing is enabled and auditing policies for the database permit
*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
*Can transport an asserted or authenticated user identity between different ABL session contexts in the same application environment
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.
* Unsealed and sealed client-principals
* Client-principal object attributes
* Client-principal object methods