Client-principal object handle

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.

Attributes

Methods

Notes

See also

AUDIT-CONTROL system handle, AUDIT-POLICY system handle, CREATE CLIENT-PRINCIPAL statement, SECURITY-POLICY system handle, SET-CLIENT( ) method, SETUSERID function, SET-DB-CLIENT function