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

• 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:
  • OpenEdge-performed — OpenEdge performs all the steps required to authenticate a user's identity. Thus, in one ABL operation OpenEdge:
    1. Submits the user's asserted identity for authentication by the user account system defined for the authentication system associated with the user's domain.
    2. Seals the client-principal object with the user's asserted identity and (if authentication is successful in Step 1) begins a login session for the user.
    3. Assigns the user's identity to an ABL session or database connection.
    Note: Step 1 can include use of an ABL authentication callback to implement or extend this user authentication step. For more information, see the sections on ABL authentication callbacks in OpenEdge Development: Programming Interfaces.
  • Application-performed — The ABL application performs all steps required to authenticate a user's identity. Thus, the ABL application:
    1. Determines and applies the criteria required to authenticate the user identity.
    2. In one ABL operation, seals the client-principal object with the user's asserted identity and (if authentication is successful in Step 1) begins a login session for the user.
    3. In another ABL operation, assigns the user's identity to an ABL session or database connection.
• 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:
  • AUDIT-EVENT-CONTEXT attribute
  • DOMAIN-DESCRIPTION attribute
  • DOMAIN-TYPE attribute
  • STATE-DETAIL attribute (if the authentication operation fails)
• 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.

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