SET-CLIENT( ) method

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.

Return type: LOGICAL

Applies to: SECURITY-POLICY system handle

Syntax

SET-CLIENT ( client-principal-handle )
client-principal-handle
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:

To set a session identity through a user authentication operation:

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:

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.

This method returns FALSE with messages returned in the ERROR-STATUS system handle when:

Notes

See also

Client-principal object handle, GET-CLIENT( ) method, SEAL( ) method, SET-DB-CLIENT function, SETUSERID function