Previous Next

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:
Return type:
Applies to:
 
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:
*
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 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:
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.
*
*
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:

Previous Next
© 2013 Progress Software Corporation and/or its subsidiaries or affiliates.