Registers a security domain in the ABL session
domain registry. The AVM uses this registry to authenticate or validate
(through a single sign-on (SSO) operation) the session identity
represented by a client-principal object, as well as the connection
identity for any OpenEdge database configured to use the session
(application) registry.
Note: This method does
not support the registration of domains to authenticate identity
for multi-tenant database connections.
Caution:
Use
caution when registering domains in the session domain registry
using the REGISTER-DOMAIN( ) method. You can introduce
the risk for a security breach by allowing the registration of rogue
domains between registering your own domains and locking the registry.
Consider using the
LOAD-DOMAINS( ) method, which loads all domain registry information directly
from the local domain registry of a connected OpenEdge database
(including multi-tenant databases).
Return type: LOGICAL
Applies
to:
SECURITY-POLICY system handle
Syntax
REGISTER-DOMAIN ( domain-name , access-code
[ , domain-description [ , domain-type ] ] )
|
-
domain-name
- A character expression that specifies the name of this security domain.
For information on the restricted character set to use for this value,
see the DOMAIN-NAME attribute entry.
-
access-code
- A character expression that specifies the secret value to use
when authenticating or validating a client-principal object that
represents a user identity in this domain. The AVM converts this
access code to UTF-8 before using it, which ensures a consistent
value regardless of code page settings.
-
domain-description
- An optional character expression that specifies a description
for this domain.
-
domain-type
- An optional character expression that specifies an application-defined
authentication system for user authentication and single-sign-on
(SSO) operations.
To authenticate or validate
a user identity against a session domain registry built using REGISTER-DOMAIN( ),
you must call the LOCK-REGISTRATION( ) method, which also locks and prevents any further registration
of domains in the domain session registry.
If you do not register
at least one domain in the session domain registry before calling
LOCK-REGISTRATION( ), the LOCK-REGISTRATION( ) method
returns TRUE. However, any attempt to seal a client-principal object against
the session registry raises a run-time error.
If successful,
this method returns TRUE. Otherwise, it returns FALSE. Note that
you cannot call REGISTER-DOMAIN( ) successfully if you
have already called the LOAD-DOMAINS( ) method or the LOCK-REGISTRATION( ) method.
The
following code fragment illustrates how to use the REGISTER-DOMAIN( )
method:
DEFINE VARIABLE name AS CHARACTER NO-UNDO.
DEFINE VARIABLE key AS CHARACTER NO-UNDO.
FOR EACH trusted-registrar:
name = trusted-registrar.name.
key = trusted-registrar.key.
SECURITY-POLICY:REGISTER-DOMAIN(name, key).
END.
SECURITY-POLICY:LOCK-REGISTRATION.
|
