Try OpenEdge Now
skip to main content
Programming Interfaces
Data Management : Application Security : Authenticating and managing user identity in ABL : Setting up and using domain registries : Building and using a session domain registry
 
Building and using a session domain registry
Typically, an ABL application builds any required session domain registry for an ABL session (including any AppServer sessions) when the ABL session first starts up. For an ABL client, this is typically a function of a startup procedure specified using the Startup Procedure (-p) startup parameter. For an AppServer agent, this is typically a function of the Startup configuration procedure for AppServers running in stateless, state-aware, or state-free mode or the Connect configuration procedure for AppServers running in state-reset mode. For more information on configuring and using AppServer Startup and Connect procedures, see the information on using AppServer configuration procedures in OpenEdge Application Server: Developing AppServer Applications.
Note: If you do not build a session domain registry, you cannot establish an ABL session or application user identity. However for a default database configuration, you can always establish a database connection identity, with or without a session registry, in order to authorize access to database tables and fields. For more information on identity usage, see Useridentity applications.
OpenEdge supports two approaches for building a session domain registry, using:
*The contents of an existing local database domain registry (recommended)
*Domain entries that you create directly within the ABL session
You can only use one of these approaches to build a domain registry for a given ABL session, and using the contents of an existing local database domain registry is the most secure approach, as described later in this section.
The SECURITY-POLICY system handle supports methods for each approach to building a session domain registry, as described in the following table.
Table 14. Methods for building a session domain registry
This SECURITY-POLICY method...
Provides this function...
LOAD-DOMAINS( integer-expression|
             logical-name|alias )
Builds the session domain registry from the local database domain registry of a specified OpenEdge database connection. (The integer-expression value specifies the database by its order of connection in the ABL session.) You can call this method multiple times to refresh the session registry from the latest contents of the same local database domain registry only. Calling this method using a different database, or using a different connection to the same database, raises an error.
You can use the session domain registry built with this method to:
*Authenticate and set the ABL session identity and the connection identity of a properly configured OpenEdge database using an unsealed client-principal (through OpenEdge-performed user authentication or ABL callback authentication) or using a sealed client-principal (through OpenEdge-performed SSO).
*Seal an unsealed client-principal using the client-principal SEAL( ) method.
If you call either the LOCK-REGISTRATION( ) method or the REGISTER-DOMAIN( ) method successfully, any call to this method fails.1 Once you call this method successfully, any call to LOCK-REGISTRATION( ) or REGISTER-DOMAIN( ) fails.
Note: This method is more secure for building the session domain registry than using the REGISTER-DOMAIN( ) method, and it is the only way to build a session registry that can be used to authenticate or validate the connection identity for an OpenEdge multi-tenant database.
LOCK-REGISTRATION( )
Locks the session domain registry against any further update using the REGISTER-DOMAIN( ) method.2 If you call this method before calling REGISTER-DOMAIN( ), the locked session registry is empty, but usable.
You must call this method before you can validate user identities using a session registry built using the REGISTER-DOMAIN( ) method.
If you call the LOAD-DOMAINS( ) method successfully before calling this method, any call to this method fails. Once you call this method successfully, the registry is usable and any call to LOAD-DOMAINS( )or REGISTER-DOMAIN( ) fails.
REGISTER-DOMAIN
   ( domain-name ,
     access-code
     [, domain-description
     [, domain-type]] )
Creates a single domain entry in the session domain registry from the parameters passed to the method:
*domain-name — Specifies the name of an OpenEdge domain, which must match the DOMAIN-NAME property of any client-principal object that you seal using this domain entry (see Table 11).
*access-code — Specifies the value to use as a MAC key for sealing a client-principal object, or for validating a client-principal object that has been sealed, against this domain entry (see Table 13).
*domain-description — Allows an informal description of the domain. Otherwise, the value is blank ("").
*domain-type — Allows you to specify the name of an authentication system for the domain. Otherwise, the value is blank ("").
You can call this method multiple times to build a session domain registry. You can then use this registry to seal an unsealed client-principal using the client-principal SEAL( ) method and to set a session identity or a connection identity for an OpenEdge database (non-multi-tenant only) using a sealed client-principal. However, OpenEdge can never use a session registry built with this method to authenticate an identity asserted with an unsealed client-principal (see LOAD-DOMAINS( ) described in this table).
If you call either the LOCK-REGISTRATION( ) method or the LOAD-DOMAINS( ) method successfully, any call to this method fails. Once you call this method successfully, any call to LOAD-DOMAINS( ) fails.
Note: The domain-description and domain-type values do not have to match the DOMAIN-DESCRIPTION and DOMAIN-TYPE attributes in a client-principal object in order to validate its identity against a domain entry.
1 Once the session domain registry is locked, it cannot be replaced or updated during the ABL session. The only way to change it is to restart the session and rebuild the registry.

2 Once the session domain registry is locked, it cannot be replaced or updated during the ABL session. The only way to change it is to restart the session and rebuild the registry.

The REGISTER-DOMAIN( ) method provides the flexibility to dynamically define an authentication domain not otherwise available in a database domain registry. However, until you call the LOCK-REGISTRATION( ) method, you run the risk of a security breach by allowing the possible registration of rogue domains in the session registry. The LOAD-DOMAINS( ) method minimizes this risk by leveraging secure mechanisms both to manage the contents of an existing database domain registry (by a security administrator) and to load the latest contents of this registry (and only this registry) into a given session domain registry.
For more information on configuring domains in an OpenEdge database, see:
*OpenEdge Getting Started: Identity Management
*The Data Administration online help
*OpenEdge Development: Basic Database Tools
*OpenEdge Management and OpenEdge Explorer: Configuring Multi-tenancy
For information on building a session domain registry, see EstablishingABL session identity in this manual.