Sets the user identity for a specified connected OpenEdge
database using an unsealed or a sealed client-principal object.
For
an unsealed client-principal object (in the INITIAL state), this
function performs a user authentication operation on the user identity
asserted by the object. If successful, the function seals the client-principal
and assigns the user identity to a specified database connection,
and if the database is multi-tenant this also sets the user's tenancy.
For
a sealed client-principal object (in the LOGIN state), this function performs
a single sign-on (SSO) operation to validate the user identity represented
by the object. If successful, the function assigns the user identity
to a database connection, and if the database is multi-tenant this
also sets the user's tenancy.
If the user identity is set
successfully and the database is multi-tenant, the connection accesses
the database through the tenant organization that is configured
for the user's domain, and the tenant information is added to the client-principal
object used to set the identity.
The function returns TRUE
if the user identity is set successfully; if unsuccessful, the function
returns FALSE, and the connection identity remains unchanged.
Syntax
SET-DB-CLIENT ( { client-principal-handle | ? }
[ , { integer-expression | logical-name |alias | ? } ] )
|
-
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 domain registry trusted by the specified
database connection. If this parameter is set to the Unknown value (?),
the current identity of affected database connections remains unchanged,
and the function unlocks and allows the connection identity to be
set using the SET-CLIENT( ) method, as described for the
setting of database parameters.
- integer-expression
|
logical-name
|
alias
| ?
- Specifies a database connection on which to set the identity as follows:
- integer-expression
- The sequence number of a connected OpenEdge database for which to set the user
identity. For example, SET-DB-CLIENT(hCP, 1) sets the user
identity associated with the specified client-principal object for the first
database connection, SET-DB-CLIENT(hCP, 2) sets the user identity
for the second database connection, and so on. If you specify a sequence number
that does not correspond to a connected database, the function returns FALSE.
- logical-name
|
alias
- The logical name or alias of a connected OpenEdge database for which to set the
user identity. These forms require a quoted character string or a character
expression. If you specify a logical name or alias that does not correspond to a
connected database, the function returns FALSE.
If you pass a valid option to identify an OpenEdge database connection, the
function operates on that OpenEdge database connection as follows:
- If the LOGIN-STATE attribute on the client-principal object is set to
"INITIAL", the function performs a user authentication operation, and if
successful, sets user identity for the database connection,
- If the LOGIN-STATE attribute on the client-principal object is set to
"LOGIN", the function performs a validation (SSO) of the user identity,
and if successful, sets the user identity for the database connection.
- If client-principal-handle is the Unknown value
(?), the current connection identity remains unchanged, and the
function removes the SECURITY-POLICY:SET-CLIENT( ) method lockout on the database
connection.
If you do not pass an option to identify the specific database connection or you
specify the Unknown value (?), the function operates on all OpenEdge
database connections as follows:
- If the LOGIN-STATE attribute on the client-principal object is set to
"INITIAL", the function performs a user authentication operation for the
first OpenEdge database connection, and if the authentication is successful, the
function:
- Sets that database connection's user identity.
- With the client-principal LOGIN-STATE attribute set to
"LOGIN", performs an SSO operation to validate and (if
successful) set the user identity for each remaining OpenEdge database
connection in the ABL session.
- If the LOGIN-STATE attribute on the client-principal object is set to
"LOGIN", the function performs an SSO operation to validate and (if
successful) set the user identity for each OpenEdge database connection in the ABL
session.
- If client-principal-handle is the Unknown value
(?), the current identity remains unchanged for all OpenEdge
databases connections, and the function removes the SECURITY-POLICY:SET-CLIENT( )
method lockout on all the connections.
Example
To
use the _login.p procedure that is provided
with ABL, you must define user IDs and passwords for users who are
authorized to access the database in user accounts associated with
authentication-enabled domains. The following sample procedure (r-login1.p)
is simplified from the _login.p procedure provided
with ABL.
r-login1.p
/* Prompt user for userid and password and set the userid */
DEFINE VARIABLE id AS CHARACTER FORMAT "x(255)" VIEW-AS FILL-IN
SIZE 50 BY 1 LABEL "User id" NO-UNDO.
DEFINE VARIABLE password AS CHARACTER FORMAT "x(255)" VIEW-AS FILL-IN
SIZE 50 BY 1 LABEL "Password" NO-UNDO.
DEFINE VARIABLE tries AS INTEGER NO-UNDO.
DEFINE VARIABLE lFound AS LOGICAL NO-UNDO.
DEFINE VARIABLE hCP AS HANDLE NO-UNDO.
/* Note: No test for _User records, as in earlier releases:
As of Release 11.0, OpenEdge can authenticate to other
user account systems in addition to the _User table. */
CREATE CLIENT-PRINCIPAL hCP. /* create a CLIENT-PRINCIPAL only once during login*/
DO ON ENDKEY UNDO, RETURN: /* return if they hit endkey */
/* Reset id and password to blank in case of retry */
ASSIGN
id = ""
password = "".
UPDATE SPACE(2) id SKIP password BLANK
WITH CENTERED ROW 8 SIDE-LABELS ATTR-SPACE
TITLE " Database " + LDBNAME("DICTDB") + " ".
/* Use SET-DB-CLIENT instead of SETUSERID */
hCP:INITIALIZE(id,?,?,password).
IF NOT SET-DB-CLIENT(hCP,"DICTDB") THEN DO:
MESSAGE "Sorry, userid/password is incorrect.".
IF tries > 1 THEN QUIT. /* Only allow 3 tries */
tries = tries + 1.
UNDO, RETRY.
END.
END.
DELETE OBJECT hCP.
hCP = ?.
HIDE ALL.
|
This procedure uses the SET-DB-CLIENT function
to authenticate the prompted user identity passed in through the
client-principal (hCP) to set the connection identity
for the database with the logical name, dictdb.
If
the value of the function is FALSE, the procedure allows the user
another try. The user has three tries to log in. The first time,
the tries variable is 0; tries is
1 the second time, and 2 the third. The third time, tries is greater
than 1 and the procedure exits without any further attempts. If
function value is TRUE, the database connection is set to the prompted
user identity. In either case, the procedure exits after deleting
the client-principal object and hiding the prompt.
Notes
- For
any errors while operating on database connections, SET-DB-CLIENT
returns FALSE, records any errors in the ERROR-STATUS system handle, and leaves the current identity for a given database
connection unchanged. Also, a validation failure when setting the
identity for a database connection does not stop SET-DB-CLIENT from
operating on other connected databases. It records an error message
for that database and attempts the operation on the next one.
- 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 assign a user identity while making a database connection,
use the CONNECT statement.
- This function also checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute on the client-principal object. If the
timestamp has expired before the function can seal (during user
authentication) or validate (during SSO) the object, the function
sets the LOGIN-STATE attribute to "EXPIRED" and returns
FALSE without changing the current connection identity.
- To set a connection 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 and PRIMARY-PASSPHRASE attribute entries).
- The domain in the registry trusted by the database connection must
be authentication-enabled. 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.
When the user authentication operation
fails for a database connection, for auditing purposes, this function
implicitly executes the AUTHENTICATION-FAILED( ) method on the client-principal and leaves the previous
connection identity unchanged.
- To set a connection identity through an SSO operation:
- The
client-principal object must be sealed and set to the LOGIN
state either explicitly by the application (using the SEAL( )
method) or implicitly by OpenEdge.
- The object must be valid according to the domain registry used by
the database connection: it 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 trusted by the database connection must
be enabled and configured with an authentication system that supports
SSO.
- To set a connection 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 function to set the connection identity.
-
For an STS-enabled database, this function always checks the user identity against the
database’s own domain registry configuration.
- For databases not using STS, the domain registry this function uses to
perform a user authentication or SSO operation depends on the database's own domain
registry configuration. If it is configured to use the application domain registry, the
function checks the user identity against the ABL session domain registry loaded using the
SECURITY-POLICY:LOAD-DOMAINS( ) method. If it is configured not to use the
application domain registry, the function checks the user identity against the database's
own local domain registry that OpenEdge loads for the connection. For more information on
domain and domain registry configuration, see OpenEdge Getting
Started: Identity Management.
- 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.
- If you do not specify a database or pass the Unknown value (?),
the user identity that this function sets for all connected databases
overrides the user identity previously set by a call to the SET-CLIENT( )
method.
- Any database connection whose user identity is set using this
function locks out the SET-CLIENT( ) method from setting
an identity for that connection until you use this function to unlock
it.
- You can also use this function, instead of the SETUSERID function, to
set the user identity for a database connection whether or not the
user account is in the _User table.
- Calling this method generates an audit event, and creates an
audit record for the event in all connected audit-enabled databases
according to each database's current audit policy settings.
- This function returns FALSE and with messages recorded in the ERROR-STATUS system handle when:
- A database connection is specified,
the client-principal object is sealed, and SSO validation of its
identity for the specified database connection fails.
- No database connection is specified, the client-principal object is
sealed, and SSO validation of its identity for any connected database
fails. In this case, ERROR-STATUS records a message for each database
connection that fails SSO validation.
- The client-principal object is unsealed and the domain configuration
is restricted to SSO operations.
- A database connection is specified, the client-principal object
is unsealed, and user authentication of its asserted identity on
the specified database connection fails.
- The client-principal object is sealed and the domain configuration
is restricted to user authentication operations.
- This function 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.
