SEAL( ) method

As part of a successful application-performed authentication operation, you can invoke this method on an unsealed client-principal in order to seal the object using the domain access code you pass as a parameter. Sealing the client-principal begins a login session to assert the identity it represents. You can then pass the sealed object as input to the SECURITY-POLICY:SET-CLIENT( ) method method or the SET-DB-CLIENT function to set the identity for the current ABL session and one or more of its database connections using a single sign-on (SSO) operation.

Note:

You only need to call the SEAL( ) method if your ABL application successfully performs its own authentication of the user’s credentials and therefore needs to initialize and seal a client-principal to represent the authenticated user identity and begin a user login session. The domain that you use to initialize the client-principal is typically configured with either the built-in _extsso authentication system or a user-defined authentication system that is enabled for SSO-only operations to validate and set a user identity. For all other supported authentication systems, such as _oeusertable, _oslocal, or user-defined authentication systems that are enabled for user authentication using an ABL authentication plugin, you can pass an appropriately initialized unsealed client-principal object directly as input to the SET-CLIENT( ) method or SET-DB-CLIENT function to authenticate the identity, seal the client-principal object, create the login session, and set the identity for the ABL session or database connection in a single user authentication operation.

You must validate and set values for the following attributes on the client-principal before you can seal the object with this method:

USER-ID attribute

DOMAIN-NAME attribute

SESSION-ID attribute

The AVM raises a run-time error if:

You do not appropriately set these attributes

The client-principal object is already sealed

You can seal a client-principal object only once per user login session. You can then use the VALIDATE-SEAL( ) method to validate the seal whenever necessary.

Once sealed, you can no longer set any attributes or user-defined properties for the object.

Return type:

LOGICAL

Applies to:

Client-principal object handle

 

Syntax 

SEAL ( domain-access-code )

domain-access-code

A case-sensitive character expression containing the access code that you have defined for the user’s domain. The AVM uses this access code to generate the message authentication code (MAC) with which to seal the client-principal object. The AVM converts this access code to UTF-8 before using it, which ensures a consistent value regardless of code page settings. A matching domain with the specified access code must be registered in a trusted domain registry in order to successfully validate the identity that is sealed in this client-principal object.

Caution:

The sealed client-principal created by this method is not usable if no trusted domain registry contains the same combination of domain name and access code. Also, note that given any client-principal that is sealed with it, this domain access code provides session and database access when validated using a single sign-on (SSO) operation against a trusted domain registry that contains a matching domain with the same access code. Therefore, Progress Software corporation strongly recommends that you take steps to hide or otherwise protect the domain access code in your ABL code from access (hacking) by unauthorized users.

If successful, this method returns TRUE. The method also sets the SEAL-TIMESTAMP attribute with the time stamp for when the client-principal object was sealed, and sets the LOGIN-STATE attribute to "LOGIN". If not successful, the method returns FALSE.

The method also checks the LOGIN-EXPIRATION-TIMESTAMP attribute. If the client-principal object expires before you can seal it, the AVM sets the LOGIN-STATE attribute to "EXPIRED" and the method returns FALSE.

Calling this method generates a login audit event and creates an audit record for the event in all connected audit-enabled databases according to each database’s current audit policy settings.

The following code fragment illustrates how to use the SEAL( ) method:

 

DEFINE VARIABLE hCP     AS HANDLE    NO-UNDO DEFINE VARIABLE key     AS CHARACTER NO-UNDO. DEFINE VARIABLE lResult AS LOGICAL   NO-UNDO. . . . CREATE CLIENT-PRINCIPAL hCp. . . . lResult = hCP:SEAL(key).

Note:

You typically call this method on an unsealed client-principal object in the INITIAL state only as a result of a successful application-performed user authentication in order to seal the object in the LOGIN state. If you want to invalidate an unsealed client-principal object in the INITIAL state because the identity it represents has failed an application-performed user authentication operation, call the AUTHENTICATION-FAILED( ) method, which seals the client-principal in the FAILED state. If you want to invalidate, and terminate the login session for, a sealed client-principal object that is in the LOGIN state, call the LOGOUT( ) method, which sets the sealed client-principal to the LOGOUT state.

See also:

AUTHENTICATION-FAILED( ) method, LOGIN-EXPIRATION-TIMESTAMP attribute, LOGIN-STATE attribute, LOGOUT( ) method, SEAL-TIMESTAMP attribute, SET-CLIENT( ) method, SET-DB-CLIENT function, VALIDATE-SEAL( ) method