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.
This method returns TRUE if successful and FALSE otherwise.
Return type: LOGICAL
Applies to:
Client-principal object handle
Syntax
SEAL ( domain-access-code )
|
-
domain-access-code
- A case-sensitive character expression containing the clear text 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.
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:
The AVM raises a run-time error if:
- You do not appropriately set these attributes.
- The client-principal object is already sealed.
- You invoke SEAL() with an encoded domain access code. (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 to validate the seal whenever necessary.
Once sealed, you can no longer set any attributes or user-defined
properties for the object.
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".
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.
