Some user authentication mechanisms require you to explicitly create and initialize a client-principal object at appropriate points in the authentication process. Typically, you create a client-principal for initialization using the CREATE CLIENT-PRINCIPAL statement (see the table ABL elements for managing user identities).

How you initialize a client-principal object for user authentication depends on whether OpenEdge (or an ABL callback) or your application is performing the user authentication. If OpenEdge performs the user authentication (when you execute either the SET-DB-CLIENT function or the SET-CLIENT( ) method on the SECURITY-POLICY system handle), you must first initialize the client-principal with user credentials and additional information that OpenEdge requires by setting appropriate values for the following client-principal attributes (see the table Client-principal object attributes you can set):

  • USER-ID
  • DOMAIN-NAME
  • PRIMARY-PASSPHRASE
  • SESSION-ID

If your application performs the user authentication, the required user credentials depend entirely on the user account system that your application uses to authenticate its user identity. If your application user account system requires different user credentials than OpenEdge requires, you might have to derive the settings of the USER-ID and DOMAIN-NAME attributes from these credentials. Also for application-performed user authentication, you typically initialize and seal the client-principal only after the user authentication has completed in order to reflect its success or failure. So, you need only set the following attributes to initialize the client-principal:

  • USER-ID
  • DOMAIN-NAME
  • SESSION-ID

You have no need to set the PRIMARY-PASSPHRASE attribute, because it is no longer needed following user authentication, and in any case, OpenEdge discards its value without a trace when you seal the object using either the SEAL( ) method (for a successful user authentication) or the AUTHENTICATION-FAILED( ) method (for an unsuccessful user authentication).

To optimize client-principal initialization, OpenEdge provides the INITIALIZE( ) method (see the table Client-principal object methods), which allows you to set all the required attributes in a single operation. Using this method, you can also set the LOGIN-EXPIRATION-TIMESTAMP attribute, which sets an expiration date and time for the client-principal. Another optimization with this method is that you can re-initialize an existing client-principal that is sealed in any state back to the INITIAL state. In a single operation, this implicitly deletes the existing object and creates a new object initialized with the specified identity settings that you can then authenticate and seal as appropriate.

Also prior to any operation that seals the client-principal, in addition to the required attribute settings, you can individually set any optional attribute values (see the table Client-principal object attributes you can set) and also set any application-defined properties that you want to associate with the login session using the SET-PROPERTY( ) method on the client-principal object handle (see the table Client-principal object methods).