ABL for managing user identity

Table 10. ABL elements for managing user identities
This ABL element...	Provides this identity management function...
Buffer object handle and buffer-field object handle	Provides LOGICAL CAN-* attributes for testing run-time data access permissions for the current database connection identity. If the current database user identity has permission to access a given database table or field using the data (CRUD) operation associated with a specific CAN-* attribute, the attribute returns TRUE. For more information, see Authorizing user access to tables and fields.
CAN-DO function	Matches a specified user ID against an ID pattern list, which you can use to authorize access to application data and features. For more information, see Authorizing access to procedures and database resources.
Client-principal object handle	When unsealed, the referenced object can be used to start a user login session for a single user identity after authenticating and sealing the user identity in the object. When sealed, the object, and copies of the object, can be used to maintain a user login session for the user identity it represents across multiple database connections or the ABL sessions of a multi-tier application. A client principal object contains a variety of information about a login session and the identity it represents, including its state and information necessary to validate and set the user identity for an ABL session or database connection using a trusted domain registry.¹, ² Using its attributes and methods, you can initialize an unsealed client principal for user authentication, transport a sealed or unsealed object between ABL sessions, and change the state of the object in various ways. For more information, see Client-principalobjects .
CONNECT statement	This statement establishes a connection to one or more databases from within an ABL procedure or class. Given a user ID and password specified using the User ID (-U) and Password (-P) connection parameters for each database, this statement authenticates the user identity for each database connection; the user's domain must be authentication-enabled. If a specified user authentication is successful, the statement establishes the database connection with the specified identity; otherwise, the connection fails. If no -U and -P parameters are specified for a database, the statement establishes the database connection with the OpenEdge default blank ("") or operating system process user identity, and uses blank only if the database allows connection to the blank user identity; otherwise, the connection fails. For each established database connection, the statement internally generates a sealed client-principal object to represent the connection identity (either using an authenticated or OpenEdge default user identity), which you can return using the GET-DB-CLIENT function.³ For more information, see Establishing database connection identity .
CREATE CLIENT-PRINCIPAL statement	Creates a client-principal object that you can use as a security token to start and maintain a given user login session. For more information, see Client-principalobjects .
GET-DB-CLIENT function	This function returns a copy of the sealed client-principal object used to set the current user identity for a specified database connection. You can use this client-principal in an SSO operation to set another database connection or ABL session identity, unless the object represents the OpenEdge default blank ("") or operating system process user identity.⁴ For more information, see Establishing database connection identity .
Progress.Lang.OERequestInfo class	OpenEdge instantiates instances of this built-in class in order to pass client context information between an AppServer client and the agents of an AppServer executing on behalf of the client running in any session model. OpenEdge automatically instantiates this class whenever a CREATE SERVER statement executes on an ABL client. Instances are accessible for both the client request and the AppServer response using attributes of the server object handle on the ABL client and attributes of the SESSION system handle on the AppServer agent. One of the members of this class is a ClientContextId property that you can use to identify context in any ABL session executing for a given client request in a multi-tier application. The ABL session (AppServer client or agent) can then use the property value to key a context database that maintains a consistent context shared by all sessions involved in the request.Progress.Lang.OERequestInfo also includes GetClientPrincipal( )and SetClientPrincipal( ), which are methods for accessing the client principal. For more information, see Establishing and managing identity for multi-tier applications and Creating and managing unique object identities .
SECURITY-POLICY system handle	This object provides methods for building a single session domain registry for authenticating a user identity for both the ABL session and all existing OpenEdge database connections.⁵, ⁶ The object also provides methods for setting and returning the session identity. For more information, see Setting up and using domain registries.
SET-CLIENT( ) method of the SECURITY-POLICY system handle	Given an unsealed client-principal object, this method authenticates the initialized user identity against the session domain registry; the user's domain must be authentication-enabled. If successful, it seals the client-principal and sets the ABL session identity to the authenticated identity; it then uses SSO to set the same user identity for any existing database connection that does not already have a connection identity assigned using the SET-DB-CLIENT or SETUSERID function. Given a sealed client-principal object, this method uses SSO to validate the associated user identity against the session domain registry. If successful, it sets the ABL session identity to the validated identity; it then uses SSO to set the same user identity for any existing database connection that does not already have a connection identity assigned using the SET-DB-CLIENT or SETUSERID function.⁷ For more information, see EstablishingABL session identity.
SET-DB-CLIENT function	Given an unsealed client-principal object and a connected OpenEdge RDBMS, this function authenticates the user identity initialized for the object; the user's domain must be authentication-enabled. If successful, the function seals the client principal and sets the database connection to the authenticated identity. Optionally, the function can attempt to set the authenticated identity on all connected databases. Given a sealed client-principal object and a connected OpenEdge RDBMS, this function uses an SSO operation to validate the associated user identity against the database trusted domain registry and set the validated identity as the new database connection identity.⁸Optionally, the function can be called to validate and set the new identity on all connected databases. For more information, see Establishing database connection identity .
SETUSERID function	Given a specified user ID and password, this function authenticates the specified user identity for an existing single database connection; the user's domain must be authentication-enabled. If successful, the function sets the authenticated identity as the current identity for the database connection, and internally generates a sealed client-principal object to represent that identity, which you can return using the GET-DB-CLIENT function. For more information, see Establishing database connection identity .
USERID function	Returns the connection identity of the specified database. This is also the default auditing identity for the database unless an option is set to use the ABL session identity. If the database is multi-tenant, the value returned is a fully-qualified user ID; otherwise, it is the account user name only. For more information, see Establishing database connection identity .

¹ Each connected OpenEdge RDBMS has a local domain registry that contains information about each domain in which a user identity can be authenticated or validated to set the database connection identity. You can optionally configure the database, instead, to use the application (session) domain registry of the ABL session to which the database is connected to provide information about these domains. For more information, see Setting up and using domain registries.

² Each ABL session can have a single session domain registry that you build at run time with information about each domain in which to authenticate and validate the user identity to set for the ABL session and (optionally) for its databases connections. For more information, see Setting up and using domain registries.

³ If a sealed client-principal object represents the OpenEdge default blank or OS process user identity (set for a database connection established without using the -U connection parameter), you cannot use the object in an SSO operation to set the blank or OS process identity for any ABL session or database connection. However, if the object represents a blank or OS user identity that you have authenticated (using the -U connection parameter, a call to the SETUSERID function, or from calling the SET-CLIENT( ) method or SET-DB-CLIENT function on an unsealed client-principal), you can use the client-principal in SSO operations to set the blank or OS user identity, both for ABL sessions and database connections.

⁴ If a sealed client-principal object represents the OpenEdge default blank or OS process user identity (set for a database connection established without using the -U connection parameter), you cannot use the object in an SSO operation to set the blank or OS process identity for any ABL session or database connection. However, if the object represents a blank or OS user identity that you have authenticated (using the -U connection parameter, a call to the SETUSERID function, or from calling the SET-CLIENT( ) method or SET-DB-CLIENT function on an unsealed client-principal), you can use the client-principal in SSO operations to set the blank or OS user identity, both for ABL sessions and database connections.

⁵ Each connected OpenEdge RDBMS has a local domain registry that contains information about each domain in which a user identity can be authenticated or validated to set the database connection identity. You can optionally configure the database, instead, to use the application (session) domain registry of the ABL session to which the database is connected to provide information about these domains. For more information, see Setting up and using domain registries.

⁶ Each ABL session can have a single session domain registry that you build at run time with information about each domain in which to authenticate and validate the user identity to set for the ABL session and (optionally) for its databases connections. For more information, see Setting up and using domain registries.

⁷ Each ABL session can have a single session domain registry that you build at run time with information about each domain in which to authenticate and validate the user identity to set for the ABL session and (optionally) for its databases connections. For more information, see Setting up and using domain registries.

⁸ Each connected OpenEdge RDBMS has a local domain registry that contains information about each domain in which a user identity can be authenticated or validated to set the database connection identity. You can optionally configure the database, instead, to use the application (session) domain registry of the ABL session to which the database is connected to provide information about these domains. For more information, see Setting up and using domain registries.