SETUSERID function (enhanced for STS)

What's new

When using an STS-enabled database, the _oeusertable authentication system is not required, and accounts do not have to be in the _User table.

Description

Authenticates a user identity for a specified database connection, verifying that the user ID and password supplied to the SETUSERID function match a user account in the _User table of the database. If they match, the database connection is set to the specified user identity and the function returns a TRUE value. If the database is multi-tenant, is also sets the user's tenancy.

If the user ID is not in the _User table or the password is incorrect, SETUSERID returns a FALSE value and does not assign the user identity to the database connection. You can also check the ERROR-STATUS system handle for any messages returned.

Syntax

userid

A literal value, field name, variable name, or expression that results in a character value that represents the user's user ID. If you use a literal value, you must enclose it in quotation marks ("").

If the user is defined in a non-default domain, this value must be a fully qualified user ID, including both the non-qualified user ID and domain separated by a domain delimiter (@). If the user is defined in the default (blank) domain, only a non-qualified user ID (without a domain delimiter) must be specified. For more information on specifying a fully qualified user ID, see the reference entry for the QUALIFIED-USER-ID attribute.

Note: The default blank domain provides backward compatibility with OpenEdge releases that do not support domains as part of a user's identity.

password

A literal value, field name, variable name, or other character expression that results in a character value that represents the user's password. If you use a literal value, you must enclose it in quotation marks ("").

Alternatively, you can encode the password using the ENCODE-PASSWORD() method. For more information, see the documentation on encoded passwords in OpenEdge Programming Interfaces.

logical-dbname

The logical name of the database on whose connection you want to check and set the user identity. The logical database name must be a character string enclosed in quotes, or a character expression. If you do not specify this argument, the compiler inserts the name of the database that is connected when the procedure is compiled. If you omit this argument and more than one database is connected, ABL raises an error.

Notes

• 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.
• 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.
• This function has the following restrictions:
  • It does not generate any audit events, such as for login and logout.
  • It can change the user identity for only one database connection at a time.
  • The domain of the user identity you want to set must be configured to use the authentication system, _oeusertable.
  • The domain of the user identity you want to set must be enabled in the _User table of the connected database.
  Note: When using an STS-enabled database, the _oeusertable authentication system is not required, and accounts do not have to be in the _User table.
• Under the following conditions, the SETUSERID function returns a value of FALSE and does not assign a user identity to the user:
  • There are no entries in the _User table.
  • There is no _User record with the same user ID as the one supplied with the SETUSERID function.
  • The password supplied with the SETUSERID function does not match the password in the _User table record of the specified user ID.
• When using the SETUSERID function, ABL returns a compiler error under the following conditions:
  • There is no database connected.
  • The logical-dbname argument is omitted, and more than one database is currently connected.
• When specifying the logical-dbname argument, you must provide the name of the logical database, not the physical database.
• SETUSERID encodes the password argument and then compares the result with the value stored in the _User._password field of the _User table.
• After SETUSERID returns a value of TRUE and assigns the authenticated user ID to a database connection:
  • ABL uses that user ID when the user compiles procedures.
  • Subsequent invocations of the USERID function for the same database connection return the assigned user ID.
• If the root user ID does not exist in the _User table, SETUSERID returns a value of FALSE when supplied with a userid of root. If the _User table does have a root entry, the user who assumes that user ID has all the privileges associated with the root user ID on UNIX.
• You must create and enable a blank user ID ("") if you want to set the user ID to a null value.
• See Learn About Identity Management, OpenEdge Programming Interfaces, and Manage the OpenEdge Database for more information on user privileges.
• Once an initial database connection is established, you can also use the SET-CLIENT() method (on the SECURITY-POLICY system handle) or the SET-DB-CLIENT function to set the user identity for the connection.
• Any database connection whose user identity is set using this function locks out the SET-CLIENT() method from setting an identity for that connection. To unlock and allow the SET-CLIENT() method to set the identity for a locked database connection, call the SET-DB-CLIENT function for the connection, passing the Unknown value (?) for its client-principal-handle parameter. This unlocking of a database connection leaves the current connection identity unchanged.
• For each user identity authenticated by the SETUSERID function, the function creates a sealed security token containing the user credentials for the database connection, which you can return as a client-principal object using the GET-DB-CLIENT function. You can then use this sealed client-principal in a single sign-on (SSO) operation to set the identity of another database connection or ABL session.
• This function returns FALSE and with messages returned in the ERROR-STATUS system handle if:
  • The format of the non-qualified user ID or domain name is invalid or the value has contains characters outside of the restricted user ID or domain name character sets (see the QUALIFIED-USER-ID attribute entry)
  • Multiple databases are connected and logical-dbname is not passed or resolves to the Unknown value (?)
  • Multiple databases are connected and logical-dbname does not refer to a connected database
• 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.