A handle to a client-principal object. Each
client-principal object is an ABL security token. This security
token contains user credentials that are used to establish a user
identity for an ABL session or database connection, and additional
information related to that identity. Once an identity is established,
it can be used to authorize such actions as accessing resources (run-time
permissions checking) and providing an auditing identity, among other
things. For a multi-tenant database connection, establishing its
identity also establishes the user's database tenancy.
You
can use a client-principal to establish identity in one of two ways, depending
on its state. If the object is unsealed (required attributes can
be modified), you can set the identity that the security token asserts
(through user authentication) for an ABL session or
database connection by authenticating this identity against specified
user accounts and creating a login session for the authenticated
user, which also seals the object against any changes to its identity.
If
the object is sealed, you can set the identity that the security
token represents (through single sign-on, or SSO)
for an ABL session or database connection by validating the object's
existing identity and login session for use by the particular ABL
session or database connection.
While the basic states of an ABL security token are unsealed or sealed, there are actually
several different states that a client-principal object can represent. You can create an ABL
security token at run time using the CREATE CLIENT-PRINCIPAL statement. For more information on the
states and uses of a client-principal object, see the Notes of this reference entry.
Syntax
client-principal-handle [ :attribute | :method ]
|
-
client-principal-handle
- A variable of type HANDLE that references a client-principal object.
-
attribute
- An attribute of the client-principal object handle.
-
method
- A method of the client-principal object handle.
Notes
- You can set the values of writable attributes and invoke methods (such as
SET-PROPERTY( )) that write data values to a client-principal object only while the object
is not sealed (unsealed). An unsealed security token is one that has not yet
been used to authenticate a user identity and is in the INITIAL state. A
sealed security token is one that is in a state other than the INITIAL
state. For more information on the possible states of a security token, see the LOGIN-STATE attribute entry.
- To set the user identity for an ABL session or OpenEdge database connection, you can use
a client-principal object together with either the SECURITY-POLICY:SET-CLIENT( ) method or
the SET-DB-CLIENT function in a user authentication or SSO
operation. The SETUSERID function also authenticates and
sets the user identity for an OpenEdge database connection and creates a security token to
store this identity. You can have only one active identity set for each ABL session or
database connection at any given point in time, and the identity of an ABL session can be
different from the identities of any and all of its database connections. You can also
retrieve the existing security token as a client-principal object for any ABL session or
database connection identity using the SECURITY-POLICY:GET-CLIENT( ) method or
GET-DB-CLIENT function.
Note: The SETUSERID
function provides limited support for user authentication and no support for SSO. It is
supported for backward compatibility. For the most complete user authentication and SSO
support, use the SET-DB-CLIENT function or the SET-CLIENT( ) method,
instead.
- A client-principal object can be used to establish identity
through user authentication or SSO, depending on its login state
(value of the LOGIN-STATE attribute).
As long as the client-principal is unsealed in the INITIAL state,
it can establish identity through user authentication. Once it is
sealed in the LOGIN state, it can establish identity through SSO.
If it is sealed in the LOGOUT, EXPIRED, or FAILED state, you can
no longer use the object to establish identity. The following figure
shows the state transitions that can occur during object operations.
Client-principal login state transitions
- The identity to be established by a client-principal must be
authenticated or validated (for SSO) using an authentication system
associated with the user's assigned OpenEdge security domain. This
domain must be enabled and registered in a trusted domain registry,
which can be one of the following:
- An ABL session registry
that you construct using methods of the SECURITY-POLICY system handle
- The local registry provided by a connected OpenEdge RDBMS
The
authentication system associated with the user's domain must support
each operation (user authentication or SSO) that you use to establish
the user's identity. For more information on authentication systems, OpenEdge
security domains, and domain registries, see OpenEdge Getting
Started: Identity Management.
- OpenEdge supports two basic forms of user authentication in
ABL using a client-principal object:
- To establish identity through an OpenEdge-performed user authentication operation, you
must first set up a trusted domain registry, which can be the local registry of a
connected OpenEdge database or a registry that you create in the ABL session, as described
previously in these notes.
Set the following required attributes of an unsealed
client-principal object (some of which have defaults):
- USER-ID attribute — The user name, which can be set from the user name (unqualified
user ID) of the QUALIFIED-USER-ID attribute value.
- DOMAIN-NAME attribute — The user's domain name, which can be set from the domain name of
the QUALIFIED-USER-ID attribute value. The specified domain must be
authentication-enabled—that is, an OpenEdge domain that is enabled for run-time
access, supports a valid source of user accounts, and is configured with an
authentication system that supports OpenEdge-performed user authentication, such as
the built-in _oeusertable or _oslocal authentication
system, or a user-defined authentication system that is enabled for authentication
using an authentication callback (see OpenEdge Development: Programming
Interfaces).
- PRIMARY-PASSPHRASE attribute — The user's password, which can have the default value of blank
("") if no passphrase is required for authentication.
- SESSION-ID attribute — A unique login session identifier, which must have a value other
than blank or the Unknown value (?) that uniquely identifies the
login session.
You can set all of these attributes in one step using the INITIALIZE( ) method. You then execute the SECURITY-POLICY:SET-CLIENT( ) method
or SET-DB-CLIENT function to invoke the authentication
operation, passing the unsealed client-principal as input. Each ABL operation
authenticates the asserted user identity, and if successful, implicitly seals the
client-principal using the domain access code that is registered for the user's domain
in the trusted domain registry, begins the user's login session, and sets the ABL
session, a database connection, or both to the authenticated identity. If successful for
the SET-CLIENT( ) method, the operation establishes the identity for the ABL session and
for any existing database connection that has not already had an identity established
using the SET-DB-CLIENT (or SETUSERID) function. If successful for the SET-DB-CLIENT
function, the operation establishes the identity for the specified database connection
and locks that database connection against any subsequent change in identity using the
SET-CLIENT( ) method. If authentication fails for any reason, including a
client-principal that has exceed any setting of its LOGIN-EXPIRATION-TIMESTAMP attribute, the operation implicitly seals the client-principal in the
appropriate non-LOGIN state (FAILED or EXPIRED).
Note: OpenEdge never
stores the value of the PRIMARY-PASSPHRASE attribute in a security token or anywhere
else. Once passed, together with other required user credentials, to the authentication
system for user authentication, OpenEdge destroys all memory of its value.
- To establish identity through an application-performed user authentication operation,
you must first set up a trusted domain registry, which can be the local registry of a
connected OpenEdge database or a separate registry that you create in the ABL session, as
described previously in these notes.
Your application determines the requirements for
authenticating a user identity, which might involve passwords, biometric profiles, and
so on. Whatever the requirements, they must result in values you can use to set the
following required attributes of an unsealed client-principal object (some of which have
defaults):
- USER-ID attribute — The user name, which can be set from the user name (unqualified
user ID) of the QUALIFIED-USER-ID attribute value.
- DOMAIN-NAME attribute — The user's domain name, which can be set from the domain name of
the QUALIFIED-USER-ID attribute value. The specified domain can be configured for an
authentication system that requires application-performed user authentication and
supports only OpenEdge-performed SSO, such as _extsso or any
user-defined authentication system that is not enabled for authentication using an
authentication callback.
- SESSION-ID attribute — A unique login session identifier, which must have a value other
than blank or the Unknown value (?) that uniquely identifies the
login session.
You can set all of these attributes in one operation using the INITIALIZE( ) method. Note that the PRIMARY-PASSPHRASE attribute is not required to initialize the
client-principal. Again, your application determines the requirements for authenticating
user identity and OpenEdge does not need to know about them.
If the application
authentication is successful, you then call the SEAL( ) method on the
client-principal object, which explicitly seals the client-principal in the LOGIN state
using the domain access code that is registered for the user's domain in the trusted
domain registry and begins the user's login session. However, if the client-principal
exceeds any setting of its LOGIN-EXPIRATION-TIMESTAMP attribute, this method implicitly seals the object in the EXPIRED state. If the
application authentication is not successful for any reason, you can then call the AUTHENTICATION-FAILED( ) method to explicitly seal the client-principal in the FAILED state.
To
set the successfully asserted and sealed identity for the current ABL session, a
database connection, or both, you pass the sealed client-principal to the
SECURITY-POLICY:SET-CLIENT( ) method
or SET-DB-CLIENT function, as appropriate. If successful for
the SET-CLIENT( ) method, the operation establishes the identity for the ABL session and
for any existing database connection that has not already had an identity established
using the SET-DB-CLIENT (or SETUSERID) function. If successful for the SET-DB-CLIENT
function, the operation establishes the identity for the specified database connection
and locks that database connection against any subsequent change in identity using the
SET-CLIENT( ) method.
- To establish identity through an SSO operation, you first need an implicitly or
explicitly sealed client-principal object that represents the user identity. You then
invoke the SECURITY-POLICY:SET-CLIENT( ) method or
the SET-DB-CLIENT function with the sealed client-principal
object as input. This SSO operation validates the domain specified for the
client-principal against the domain's access code in the trusted domain registry. If
successful for the SET-CLIENT( ) method, the operation establishes the identity for the
ABL session and for any existing database connection that has not already had an identity
established using the SET-DB-CLIENT (or SETUSERID) function. If successful for the
SET-DB-CLIENT function, the operation establishes the identity for the specified database
connection and locks that database connection against any subsequent change in identity
using the SET-CLIENT( ) method.
- When any user authentication or SSO operation successfully sets
the user identity for a multi-tenant database connection, the operation
also establishes the user's database tenant organization as defined
by the user's domain. In addition, this operation stores the tenant
information for this database connection in the client-principal
object, including the database name, tenant name, and a tenant ID,
which together uniquely identify the tenant for this particular
database connection. This unique tenancy thus distinguishes tenants
among connections to multiple multi-tenant databases that share
the same user identity for more than one connection. This tenant
information can be returned using the DB-LIST attribute, TENANT-ID( ) method, and TENANT-NAME( ) method of
the client-principal object for every database connection that has
been set to the user identity using this instance of the client-principal
object only. This information can be returned for a database that
has nothing to do with the current ABL session, because the same
client-principal instance can be used to establish identity in multiple
ABL sessions where it can accumulate tenant information for multi-tenant
database connections across sessions.
- In addition to the invoking the SET-CLIENT( ) method or SET-DB-CLIENT function with an
unsealed client-principal, OpenEdge performs a user authentication operation that creates
a sealed security token for a specified database connection from asserted user credentials
using the SETUSERID function or when asserting identity with
the User ID (-U) and Password (-P) connection parameters to the CONNECT statement and the AVM startup command line. During
any OpenEdge-performed user authentication operation, OpenEdge assigns the values
of the following attributes (if not already set) from the domain configuration before
sealing the associated security token:
- At any point during a user login session, you can log the user
out by invoking the LOGOUT( ) method on
the sealed client-principal object (in the LOGIN state) that represents
the user's identity. This method thus changes the object's state
from LOGIN to LOGOUT.
- You can use the EXPORT-PRINCIPAL( ) method and IMPORT-PRINCIPAL( ) method to transport a sealed or unsealed security token
from one ABL session to another, where its identity can be authenticated
during login or validated during SSO operations, as appropriate.
For an unsealed client-principal that you export outside the current
session, you can also encrypt any setting of the PRIMARY-PASSPHRASE attribute. For more information, see the description of how
to encrypt passwords in the ENCRYPT-AUDIT-MAC-KEY( ) method entry.
- Certain methods invoked on or using a client-principal object generate
audit events. For more information, see the AUDIT-EVENT-CONTEXT attribute entry.