What's new

After an STS-enabled database is connected to a given session, you cannot call the SEAL( ) method on the client principal with an encoded domain access code. After an STS-enabled database connection is made, you can only call SEAL( ) with a clear text domain access code.

Description

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 or the SET-DB-CLEINT 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 or if the authentication is done via STS, 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.
  • An STS-enabled database is already connected to a session, and you invoke SEAL( ) with an encoded domain access code. This restriction prevents unauthorized access to the database using a client principal generated locally. After an STS-enabled database connection is made, you can only call SEAL( ) with a clear text domain access code.

You can seal a client-principal object only once per user login session. You can then use the VALIDATE-SEAL( ) method (enhanced for STS) 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 (enhanced for STS) 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

LOGIN-STATE attribute (enhanced for STS), VALIDATE-SEAL( ) method (enhanced for STS)