SET-DB-CLIENT function

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.

Note:

Using this function overrides any user identity previously set for the database connection by either the SECURITY-POLICY:SET-CLIENT( ) method or the SETUSERID function.

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:

1.	Sets that database connection's user identity.

2.	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.

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.

See also 

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