Sets the identity, using an unsealed or a sealed client-principal object, for the current ABL session, and for all connected and unlocked OpenEdge database connections.
For an unsealed client-principal object (in the INITIAL state)—this method performs a user authentication operation on the user identity asserted by the object. If successful, the method seals the client-principal and assigns the user identity to the ABL session.
For a sealed client-principal object (in the LOGIN state)—this method performs a single sign-on (SSO) operation to validate the user identity represented by the object. If successful, the method assigns the user identity to the ABL session.
If the ABL session identity is set successfully, the method performs an SSO operation to validate and (if successful) set the user identity for each OpenEdge database connection in the ABL session that has not been previously set using the SET-DB-CLIENT function or the SETUSERID function.
Note: Any subsequent calls to either the SETUSERID or SET-DB-CLIENT functions override the user identity for any database connections set by SET-CLIENT( ) and locks these connection identities from any further change by this method unless you unlock each connection. For more information on unlocking a database connection identity, see the SET-DB-CLIENT function reference entry.
A handle to a client-principal object. If the client-principal object is unsealed, it must be initialized with the attribute values required by the SEAL( ) method in addition to any PRIMARY-PASSPHRASE attribute value required to authenticate the asserted user identity. If the object is sealed, it must be sealed with a domain access code that is the same as the access code configured for the user's domain stored in the session domain registry and in the domain registry trusted by each database connection to validate the user's identity. If the handle value is set to the Unknown value (?), the method raises a run-time error and the current session and database connection identities remain unchanged.
If the method returns TRUE, user authentication or validation is successful, the specified identity is set for the current ABL session, and OpenEdge attempts to set the identity using SSO for each unlocked OpenEdge database connection. If validation of the identity fails for any unlocked database connection, the method also returns TRUE, but the ERROR-STATUS system handle returns a message for each database connection that failed SSO validation.
If the method returns FALSE, the identity of the session remains unchanged, and OpenEdge does not set the identity for any existing database connections.
Within a transaction on a:
Multi-tenant database — Any attempt to set an identity for the connection that changes the current database tenancy raises a run-time error.
Non-multi-tenant database — As a best practice, Progress Software recommends that you not set a new identity for the connection.
To set a session identity through a user authentication operation:
The client-principal object must be unsealed (in the INITIAL state).
The required attributes must be properly set (see the SEAL( ) method entry).
The DOMAIN-NAME attribute must be set to the name of an authentication-enabled domain that is registered in the session domain registry. This can include a domain configured with a user-defined authentication system that has an ABL authentication plugin enabled. For information on OpenEdge support for domains and domain configuration, see OpenEdge Getting Started: Identity Management.
Note: To set a session identity when the authentication system is your ABL application, you must manually authenticate the user credentials for the client-principal object, explicitly call the SEAL( ) method to seal the object, and perform an SSO operation using this method to set the session identity.
If the user authentication operation fails, for auditing purposes, this function implicitly executes the AUTHENTICATION-FAILED( ) method on the client-principal and leaves the previous session and any database connection identities unchanged.
To set a session identity through an SSO operation:
The client-principal object must be sealed and in the LOGIN state.
The object must be valid according to the session domain registry: the object must be sealed using the access code defined for a registry domain whose name matches the domain name stored in the object.
The domain in the registry must be configured with an authentication system that supports SSO.
If the LOGIN-STATE attribute for a sealed client-principal object is not set to "LOGIN", the AVM raises a run-time error and the current user identity remains unchanged.
This method also checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute on the client-principal object. If the timestamp has expired before the method can seal (during user authentication) or validate (during SSO) the object, the method sets the LOGIN-STATE attribute to "EXPIRED" and returns FALSE.
The client-principal object is sealed and the domain configuration is restricted to user authentication operations.
The client-principal object is sealed and SSO validation of its identity for the current ABL session fails.
The client-principal object is unsealed and the domain configuration is restricted to SSO operations.
The client-principal object is unsealed and user authentication of its asserted identity for the current ABL session fails.
Notes
To rely on the SET-CLIENT( ) method for all identity settings, do not use the SETUSERID function, SET-DB-CLIENT function, or the CONNECT statement to set the connection identity or you must unlock every database connection whose identity has been set with these mechanisms.
After a user identity is set for a database connection, the AVM uses that identity to determine if the user has permission to access tables and fields in that particular database.
When a user identity is set for an application with at least one connected audit-enabled database, this method generates an audit event and creates an audit record for the event in every connected audit-enabled database on which the identity was set according to each database's current audit policy settings.
You can use this method, instead of the SETUSERID function, to set a database connection identity whether or not the user account is in the _User table.
This method does not attempt set the connection identity for the foreign data source of a DataServer connection. However, it does attempt to set the connection identity for the OpenEdge schema holder database.
Multi-tenant database — Any attempt to set an identity for the connection that changes the current database tenancy raises a run-time error.