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:
-
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.
This method
returns FALSE with messages returned in the ERROR-STATUS system handle when:
- 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.