The client-principal object that you create has a number of attributes that you can set and methods that you can invoke to initialize it for user authentication. The most important of these for an OpenEdge-performed user authentication are the USER-ID, DOMAIN-NAME, PRIMARY-PASSPHRASE, and SESSION-ID attributes. Note that the USER-ID attribute actually specifies the non-qualified user ID (or user name). You can initialize both the USER-ID and DOMAIN-NAME attributes using a single fully qualified user ID that you assign to the QUALIIED-USER-ID attribute. For more information on setting a fully qualified user ID see Entering user credentials in OpenEdge. For information on setting the SESSION-ID attribute, see Exporting and importing a client-principal object. Other possible initialization settings of a client-principal object include attributes to specify:

  • DOMAIN-DESCRIPTION attribute - Domain description
  • AUDIT-EVENT-CONTEXT attribute - Audit context information
  • LOGIN-EXPIRATION-TIMESTAMP attribute - Date and time of login expiration
  • CLIENT-WORKSTATION, CLIENT-TTY, and LOGIN-HOST attributes - Session login environment
  • ROLES attribute - List of user role names defined in the format of a permissions list passed to the CAN-DO function.
  • SET-PROPERTY( ) , GET-PROPERTY( ) , and LIST-PROPERTY-NAMES( ) methods - For setting application-defined name-value pairs that can hold any useful login information

There are additional attributes for returning the status of a client-principal object and its login session, such as the DOMAIN-TYPE, LOGIN-STATE, STATE-DETAIL, and SEAL-TIMESTAMP attributes. Yet another set of attributes track a user's tenancy for multi-tenant database connections during a login session (see Managing identity for multi-tenancy).

Once you complete a user authentication operation and the object is sealed (starting a login session), you can no longer directly modify its attributes or other settings. When OpenEdge creates a client-principal as it connects to a database, it sets only the most important attributes before sealing the object. You can re-initialize a sealed object to authenticate a new login session using the INITIALIZE( ) method, which creates a new unsealed one, but the old security token is discarded and cannot be re-used to set the user's identity. Otherwise, a login session otherwise remains active until you invoke the LOGOUT( ) method or the AUTHENTICATION-FAILED( ) method on the client-principal object to change its LOGIN state.