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:
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.
