Try OpenEdge Now
skip to main content
ABL Reference
ABL Syntax Reference : CREATE CLIENT-PRINCIPAL statement
 

CREATE CLIENT-PRINCIPAL statement

Creates an instance of a client-principal object at run time in the INITIAL state (see the LOGIN-STATE attribute entry). Each client-principal instance is a security token that contains user credentials specific to one user login session. This login session can be used to set the user identity for one or more ABL sessions, one or more database connections, or an entire ABL application. This user identity must be defined in a security domain that is registered in a trusted domain registry that is used to authenticate or validate that identity.
Note: You use a client-principal object with the SET-CLIENT( ) method or SET-DB-CLIENT function to set the user identity for an ABL session or OpenEdge database. You can set only one user identity at any one point in time for each ABL session or database connection. However, you can maintain multiple client-principal instances for any number of user identities that you need to set and maintain during an application.

Syntax

CREATE CLIENT-PRINCIPAL client-principal-handle
  [ IN WIDGET-POOL widget-pool-name]
client-principal-handle
A variable of type HANDLE that contains the handle to the client-principal object.
IN WIDGET-POOL widget-pool-name
An expression of type CHARACTER that evaluates, at run time, to the name of the widget pool in which the client-principal is created.
Note: Widget pool names are not case sensitive.
*To use a client-principal object in the INITIAL state, you must set the required attributes to store the user's credentials and provide access to a domain registry that you trust to authenticate or validate the identity it represents for the ABL session or a database connection:
*The local domain registry for a database connection is automatically loaded by OpenEdge and available to verify any identity assigned to the connection. Using OpenEdge data administration tools, you can also configure the OpenEdge database to ignore its local domain registry after the initial connection is established, and use the ABL session domain registry to securely set its connection identity. This allows multiple database connections to share a single domain registry to validate and set their connection identities
*You can use the LOAD-DOMAINS( ) method on the SECURITY-POLICY system handle to load the ABL session domain registry from the local domain registry of a connected OpenEdge database. This automatically prevents the registration or loading of domains from outside the this database, but enables all database connections to share the same registry built from a single connected database. This method creates a session domain registry that can be used to authenticate or validate identity for both multi-tenant and non-multi-tenant database connections.
*If you have not already loaded the ABL session registry using LOAD-DOMAINS( ), you can use the REGISTER-DOMAIN( ) method on the SECURITY-POLICY system handle to register and load domains individually into the session domain registry. You can then prevent additional domains from being loaded into the session registry using the LOCK-REGISTRATION( ) method on the SECURITY-POLICY system handle. An ABL session domain registry loaded and locked using REGISTER-DOMAIN( ) and LOCK-REGISTRATION( ) does not allow you to authenticate or validate identity for multi-tenant database connections. These methods only allow you to build a session domain registry that can be shared among non-multi-tenant database connections.
*If you do not specify a widget pool name, the object is created in the Session unnamed widget pool (not in the closest unnamed widget pool). The object goes away when its widget pool goes away or when you delete it using the DELETE OBJECT statement.

See also

Client-principal object handle, LOAD-DOMAINS( ) method, LOCK-REGISTRATION( ) method, REGISTER-DOMAIN( ) method, SET-CLIENT( ) method, SET-DB-CLIENT function