An unsealed client-principal object provides several attributes that you can, or must, set for various functional and informational purposes. Whether or not you set them, writeable client-principal attributes become read-only once the object is sealed.

Before sealing a client-principal object that you have created, you must set several OpenEdge-required attributes and several optional attributes (depending on your application), as described and listed in the following table. Unless otherwise noted, these attributes hold CHARACTER values. All references to a "user" indicate the user associated with the user identity that this client-principal object represents.

Table 1. Client-principal object attributes you can set
This attribute... Sets this value...
Required attributes
DOMAIN-NAME (Required) The name of the OpenEdge security domain in which the user identity is to be authenticated. This domain identifies the authentication system used to authenticate the non-qualified user ID specified by the USER-ID attribute. You must set this value before sealing the object and starting a login session. To seal the object and use it to establish identity, this value must be identical to one of the following and made available through a trusted domain registry:
  • The Name setting for a domain entry created in an OpenEdge database using the Domains dialog box in the Data Administration tool. This domain must also be enabled.
  • The Domain Name setting for a domain entry created in an OpenEdge database using the Domains editor of the Database Administration Console. This domain must also be enabled.
  • A domain name that you specify for a domain entry that you create at run time in the ABL session domain registry using the REGISTER-DOMAIN( ) method of the SECURITY-POLICY system handle (see Setting up and using domain registries.)
For basic information on configuring domains and domain registries in OpenEdge, see Introduction to Identity Management. For information on accessing domains to authenticate a database connection identity, see Establishing database connection identity. For information on accessing domains to authenticate an ABL session identity, see Establishing ABL session identity.
Note: Unless you create a session registry using the REGISTER-DOMAIN( ) method, it is up to the security administrator to ensure that the domain name you specify actually corresponds to the authentication system that you use to authenticate the user ID and that the domain is also configured with an appropriate domain access code.
SESSION-ID (Required) A value to uniquely identify the user login session represented by the client-principal object. This value must be set before sealing the object and starting a login session.

You can set this to any value, but you should set it to a unique value to identify the login session in session audit trails. To obtain a unique value, you can use the ABL GENERATE-UUID function (see Creating and managing unique object identities).

Otherwise, OpenEdge provides other ways to obtain a unique value. If you call the INITIALIZE( ) method on the client-principal without explicitly setting this value, OpenEdge automatically sets it to a unique value.

If you want to associate the login session with a local application server session, you can also use the value of the SERVER-CONNECTION-ID attribute in a session-managed application or the ClientContextID property on the Progress.Lang.OERequestInfo object for any application session model (both available using the SESSION handle). For more information on when and how you might do this, see Establishing and managing identity for multi-tier applications.
USER-ID (Required) The non-qualified user ID (account user name) of the user represented by this client-principal object. This is the user ID that must be authenticated in the domain specified by the DOMAIN-NAME attribute, whether OpenEdge, your application, or an ABL callback performs the authentication. You must set this value before sealing the object and starting a login session.
Note: The security administrator must ensure that the OpenEdge domain specified by the DOMAIN-NAME attribute is configured with the authentication system used to authenticate this user ID.
Optional attributes
AUDIT-EVENT-CONTEXT When auditing is enabled, an application-defined value that OpenEdge stores in the _Event-context field of each audit event record generated by a client-principal SEAL( ), LOGOUT( ), or AUTHENTICATION-FAILED( ) method, or by an OpenEdge-performed user authentication using the SET-DB-CLIENT function or the SET-CLIENT( ) method on the SECURITY-POLICY system handle. You can set this value or leave it empty. If you do not set this value, for any ABL operation on the client-principal that generates an audit event, OpenEdge sets the attribute to any audit context value that the security administrator has specified for the user's domain (DOMAIN-NAME) configuration.
CLIENT-TTY The name of the terminal display for the user's login session. You can set this value or leave it empty. OpenEdge does not otherwise set this attribute.
CLIENT-WORKSTATION The name of the host workstation on which the user is working. You can set this value or leave it empty. OpenEdge does not otherwise set this attribute.
DOMAIN-DESCRIPTION A description of the domain in which the user specified by USER-ID is authenticated. You can set this value or leave it empty. If the attribute is empty, OpenEdge assigns any domain description that the security administrator has specified for the authentication domain configuration when you invoke the SEAL( ) or AUTHENTICATION-FAILED( ) method, or when you have OpenEdge perform the user authentication by invoking the SET-DB-CLIENT function, or by invoking the SET-CLIENT( ) method on the SECURITY-POLICY system handle.
DOMAIN-TYPE The name of the authentication system used to authenticate the user specified by USER-ID. You can set this value or leave it empty. If the attribute is empty, OpenEdge assigns the value from the authentication system name configured for the user's domain (DOMAIN-NAME) when you invoke the SEAL( ) or AUTHENTICATION-FAILED( ) method, or when you have OpenEdge perform the user authentication by invoking the SET-DB-CLIENT function, or by invoking the SET-CLIENT( ) method on the SECURITY-POLICY system handle.
LOGIN-EXPIRATION -TIMESTAMP A DATETIME-TZ value that specifies when the client-principal object (and any login session started with it) expires. At this point, OpenEdge sets the LOGIN-STATE attribute (see the following table) to "EXPIRED", the client-principal can no longer represent a user identity, and any started user login session for the object ends. OpenEdge detects that the specified time has passed only during ABL operations when it tries to seal the client-principal, validate the identity the object represents, or import the object from outside the ABL session. If you do not set this value, OpenEdge leaves it set to the Unknown value (?) and never sets the object to the EXPIRED login state.
LOGIN-HOST The name of the host workstation on which the user's identity was authenticated. You can set this value or leave it empty. OpenEdge does not otherwise set this attribute.
PRIMARY-PASSPHRASE The secret passphrase (or password) required to authenticate the user's ID (account name) specified by the USER-ID attribute. You must set this write-only value, along with all required attributes, before having OpenEdge authenticate the user identity (by passing the unsealed client-principal to the SET-DB-CLIENT function or to the SET-CLIENT( ) method on the SECURITY-POLICY system handle). For all other operations you invoke with the unsealed client-principal, including explicitly sealing the object with the SEAL( ) or AUTHENTICATION-FAILED( ) method, setting this value is entirely optional. Note that for a user authentication performed by your ABL application, this operation can be completely independent of the client-principal, which you typically seal to start a login session only after the authentication is successful.
Note: Your application can only write values to this attribute, which can never be read. Also, any value you set is discarded without a trace by OpenEdge at the point the object is sealed, whether by your application following an application-performed authentication, or by OpenEdge following an OpenEdge-performed authentication, and whether or not the authentication is successful.
QUALIFIED-USER-ID The user's fully-qualified user ID, which consists of the USER-ID attribute (account user name) value followed by the DOMAIN-NAME attribute value separated by the '@' character (account-name@domain-name). If you set the QUALIFIED-USER-ID attribute, OpenEdge sets USER-ID and DOMAIN-NAME accordingly, and if you set USER-ID and DOMAIN-NAME, OpenEdge sets QUALIFIED-USER-ID accordingly. OpenEdge supports certain patterns for setting and reading this value, which set or return default values for the USER-ID and DOMAIN-NAME attributes, appropriately. For more information, see the entry for the QUALIFIED-USER-ID attribute in ABL Reference.
ROLES A comma-separated string of domain roles for the user identity associated with this object. You can set this value or leave it empty. OpenEdge does not otherwise set this attribute.

Some client-principal attributes are read-only and can never be set, even for an unsealed client-principal. For a given client-principal object, OpenEdge sets the read-only values of these attributes on behalf of the application, depending on client-principal method calls and other operations.

The following table describes these read-only attributes (other than HANDLE, INSTANTIATING-PROCEDURE, and TYPE, which are common to all handle-based objects). For more information on how these attributes are set, see the table ABL elements for managing user identities, the above table, and the table Client-principal object methods.

Table 2. Client-principal object attributes are read-only
This attribute... Returns this value...
DB-LIST A comma-separated list of logical names of all OpenEdge multi-tenant databases for which a connection identity has been set using this sealed client-principal object in one or more ABL sessions. This list ignores all connections to non-multi-tenant databases.
LOGIN-STATE A CHARACTER value that represents the state of the client-principal object and any user login session started with it. The following describes the valid values for LOGIN-STATE and the possible transitions from one state to another:
  • "INITIAL" — (Default value) The state of an unsealed client-principal after it is created (either explicitly when using the CREATE CLIENT-PRINCIPAL statement or automatically when a CREATE SERVER statement executes on an ABL client), or after calling the INITIALIZE( ) method on an existing sealed or unsealed client-principal. From "INITIAL", LOGIN-STATE can transition to "LOGIN", "FAILED", "EXPIRED", or "LOGOUT".
  • "LOGIN" — The state when an unsealed client-principal is successfully sealed using the SEAL( ) method (see the table Client-principal object methods), the SET-CLIENT( ) method on the SECURITY-POLICY system handle, or the SET-DB-CLIENT function (see the table ABL elements for managing user identities). At this point OpenEdge starts a login session and the object can be used to represent an authenticated user identity. From "LOGIN", LOGIN-STATE can transition to "EXPIRED", or "LOGOUT".
  • "EXPIRED" — The state when OpenEdge detects that the current date and time is later than a DATETIME-TZ setting of the LOGIN-EXPIRATION-TIMESTAMP attribute (see the above table). In that event, OpenEdge sets this value and seals the client-principal, which can no longer be used to represent a user identity. OpenEdge cannot transition to another state.
  • "FAILED" — The state after the AUTHENTICATION-FAILED( ) method is invoked on the unsealed client-principal, or after an OpenEdge-performed user authentication operation fails on the unsealed object using the SET-CLIENT( ) method or the SET-DB-CLIENT function. In that event, OpenEdge sets this value and seals the client-principal, which can no longer be used to represent a user identity. OpenEdge cannot transition to another state.
  • "LOGOUT" — The state after OpenEdge terminates the login session, and the sealed client-principal can no longer be used to represent a user identity. OpenEdge cannot transition to another state.
  • "SSO" — The state when the client principal was sealed by a non-OpenEdge user authentication process. From "SSO", LOGIN-STATE can transition to "EXPIRED", or "LOGOUT".
STATE-DETAIL A CHARACTER value that provides more detailed information about the most recent setting of the LOGIN-STATE attribute. OpenEdge also sets this attribute to any reason parameter value that you pass to the AUTHENTICATION-FAILED( ) method (see the table Client-principal object methods).
SEAL-TIMESTAMP A DATETIME-TZ value that represents the date and time when the client-principal object was sealed and a user login session was started (changing the object login state from INITIAL to LOGIN). OpenEdge sets this value when you authenticate a user identity and implicitly or explicitly seal an unsealed client-principal by calling the SET-DB-CLIENT function, the SET-CLIENT( ) method on the SECURITY-POLICY system handle (see the table ABL elements for managing user identities), or the SEAL( ) method (see the table Client-principal object methods).#rfi1432001569601__def_02
1 OpenEdge also implicitly creates a client-principal object and sets this value when it successfully authenticates the user identity specified using the User ID (-U) and Password (-P) connection parameters (on the command line or in the CONNECT statement) and seals the object.