REGISTER-DOMAIN( ) method

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.

See also:

LOAD-DOMAINS( ) method, LOCK-REGISTRATION( ) method