After you create a client principal object, in addition to setting writeable attributes, you can set and read any number of application-defined properties using methods on the object handle. After all required attributes and application-defined properties have been set, you can invoke additional ABL methods and functions to start and manage a user login session. The following table describes all the methods that you can invoke on the client-principal object, organized according to usage. For more information on authenticating and setting user identity with a client-principal, see Authenticating and setting user identity.

Table 1. Client-principal object methods
This method... Provides this function...
Application property set and get methods 
GET-PROPERTY( property-name )
 Given the name of an application-defined property (property-name, expressed as a case-sensitive, quoted string), returns the string value assigned to that property using the SET-PROPERTY( ) method. 
LIST-PROPERTY-NAMES( )
 Returns a comma-separated list of the names for all application-defined properties set using the SET-PROPERTY( ) method. 
SET-PROPERTY( property-name,
              property-value )
 Defines a property in the client-principal object with a name (property-name) specified by a case-sensitive, quoted string and a value specified by a character expression (property-value). You can call this method only once for each property you define in the object, preventing the definition of multiple properties with the same name.
Login session management methods 
AUTHENTICATION-FAILED (
  [ reason ] )
 Indicates that the user ID associated with an unsealed client-principal object (in the INITIAL state) cannot be authenticated. After calling this method, the LOGIN-STATE attribute is set to "FAILED", the client-principal object is invalidated, its attributes and properties cannot be changed, and the object is sealed but cannot be used to represent a user identity.

Calling this method also writes the value of any character expression you provide for the reason parameter to the STATE-DETAIL attribute.

If auditing is enabled and auditing policies permit, the method generates an audit event record to indicate a user login failure.		 
EXPORT-PRINCIPAL( )
 Converts and returns a sealed or unsealed client-principal object, including all of its attribute and property settings, as a RAW value. You can then store this value or pass it as a remote procedure parameter that an application server session can use to create a copy of the object using the IMPORT-PRINCIPAL method. Thus, this method allows you to transport the asserted or authenticated user identity represented by a client-principal object from one ABL session to another. 
IMPORT-PRINCIPAL( expression )
 Given a RAWexpression that represents a sealed or unsealed client-principal object (as output from the EXPORT-PRINCIPAL( ) method), sets the current handle to a copy of the exported client-principal object. You can then use the copy as appropriate for the exported object. 
INITIALIZE( 
  qualified-user-id 
  [, session-id 
  [, expiration 
  [, primary-passphrase]]] )
 Sets an existing unsealed or sealed client-principal object to the INITIAL state, with attribute values initialized from the following parameter list:
  • qualified-user-id — (Required) Sets the QUALIFIED-USER-ID attribute, which in turn sets the USER-ID and DOMAIN-NAME attributes.
  • session-id — If specified, sets the SESSION-ID attribute. By default, OpenEdge initializes SESSION-ID to a globally unique value (GUID).
  • expiration — If specified, sets the LOGIN-EXPIRATION-TIMESTAMP attribute to a date and time after which any use sets the object to the EXPIRED state. Otherwise, OpenEdge sets the Unknown value (?) and the object has no expiration date and time.
  • primary-passphrase — If specified, sets the PRIMARY-PASSPHRASE attribute for user authentication. Otherwise, OpenEdge sets the Unknown value (?) and no password is set for user authentication.
All other attributes of the object are reset to their default values. Any prior list of application properties and their settings are removed from the object.

This method allows you to re-use an existing client-principal for a different identity rather than creating an additional object to manage in the session. You can thus represent different consecutive identities with a single object that you need only delete once when all identity management with the object is complete.

 
LOGOUT( )
 Indicates that the user ID associated with a sealed client-principal object (in the LOGIN state) has logged out of its user login session. After calling this method, the LOGIN-STATE attribute is set to "LOGOUT", the client-principal object is invalidated, its attributes and properties cannot be changed, and the object can no longer be used to represent a user identity.

If auditing is enabled and auditing policies permit, the method generates an audit event record to indicate the user logout.

 
SEAL( domain-access-code )
 Given a character expression (domain-access-code), seals the unsealed client-principal object and starts a user login session for the user identity it represents. This method also generates an optional user login session record in all connected databases. Before calling this method, all the required attributes must be set (see the tableClient-principal object attributes you can set).

Typically, use of this method assumes that your application has authenticated the user identity that it represents, though such authentication is not required. For users in an authentication-enabled domain, you can have OpenEdge authenticate and seal the client-principal in a single operation using the SET-CLIENT( ) method on the SECURITY-POLICY system handle or the SET-DB-CLIENT function. These methods also set the authenticated user identity for supported security systems (the ABL session or its current database connections).

Sealing a client-principal generates a digital seal that is stored with the object in the form of a message authentication code (MAC), which is based on the value of domain-access-code (MAC key) and the contents of the object. This seal is used to validate the client-principal object before setting user identities with it. To generate a validating seal, you must ensure that the value of domain-access-code is identical to the access code defined for the security domain that is specified by the DOMAIN-NAME attribute and stored in the trusted domain registry (see Authenticating and setting user identity).

Calling this method also sets the SEAL-TIMESTAMP attribute and checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute (see the tableClient-principal object attributes you can set). If the client-principal has expired, OpenEdge sets the LOGIN-STATE attribute to "EXPIRED", making the object unusable to represent a user identity. Otherwise, it sets the attribute to "LOGIN", and if auditing is enabled and auditing policies permit, it generates an audit event record to indicate a valid user login.

After calling this method successfully, you can pass the sealed client-principal object in a call to the SET-DB-CLIENT function or the SET-CLIENT( ) method on the SECURITY-POLICY system handle, which then validates the user identity the object represents and assigns the validated identity to all supported security systems.		 
TENANT-ID( db-exp )
 Returns the tenant ID that is associated with the user identity sealed in the client-principal and assigned to a connection to the multi-tenant database specified by db-exp. The current client-principal object contains the tenant ID associated with the specified database.

In order to contain this tenant ID, the current client-principal must have been used to assign its user identity to the database connection in the current ABL session, or in another ABL session from which the object was returned to the current ABL session. Once the connection identity is assigned, OpenEdge stores the ID for the tenant associated with the connection identity in the client-principal. However, the specified database does not have to be currently connected to return the associated tenant ID. Once a tenant ID for a database connection is stored in the client-principal, it cannot be removed and can be returned for the duration of the corresponding user login session.

 
TENANT-NAME( db-exp )
 Returns the tenant name that is associated with the user identity sealed in the client-principal and assigned to a connection to the multi-tenant database specified by db-exp. The current client-principal object contains the tenant name associated with the specified database.

In order to contain this tenant name, the current client-principal must have been used to assign its user identity to the database connection in the current ABL session, or in another ABL session from which the object was returned to the current ABL session. Once the connection identity is assigned, OpenEdge stores the name for the tenant associated with the connection identity in the client-principal. However, the specified database does not have to be currently connected to return the associated tenant name. Once a tenant name for a database connection is stored in the client-principal, it cannot be removed and can be returned for the duration of the corresponding user login session.

 
VALIDATE-SEAL( 
  [ domain-access-code ] )
 Validates the MAC seal generated for a client-principal object by the SEAL( ) method. To call this method on a sealed client-principal object, the LOGIN-STATE attribute must be set to "LOGIN". You typically validate the seal on a sealed client-principal object after you have imported it (using the IMPORT-PRINCIPAL( ) method) from some external storage that is beyond the exclusive control of your application or whose integrity is otherwise questionable. To successfully validate the seal, you must provide the method with a domain access code value in one of the following ways:
  • Pass it a parameter (domain-access-code) whose value is identical to the domain access code used to seal the object.
  • Do not pass a value and ensure that the session domain registry contains a domain entry matching the security domain defined for the client-principal object by the DOMAIN-NAME attribute and that the entry includes a domain access code whose value is identical to the access code used to seal the object (see Setting up and using domain registries).
Calling this method also checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute (see the tableClient-principal object attributes you can set). If the client-principal object has expired, ABL sets the LOGIN-STATE attribute to "EXPIRED", making the object unusable to represent a user identity.