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.