OpenEdge security domains are modeled on a security domain pattern where servers, applications, and databases all trust a common security token that is issued to an authenticated user account that is recognized as a valid user of the domain. In an OpenEdge environment a OpenEdge security domain (also called an OpenEdge domain, or simply domain) constitutes a collection of PAS for OpenEdge ABL applications, OpenEdge Database instances, SQL-92, and OpenEdge Authentication Gateway components that all trust a common CLIENT-PRINCIPAL security token that is issued to users who have been authenticated to a domain-trusted user account. The result is the ability to isolate a user’s access to the OpenEdge components of one domain from users of other domains.

The introduction of OpenEdge domains resulted from enabling multi-tenant support throughout the OpenEdge products. OpenEdge domains are an ideal security solution for maintaining the virtual isolation needed for securing applications and their data in multi-tenant SaaS operations. The result is that OpenEdge components now support multiple OpenEdge domains for their run-time user identity management and component access checking. Regardless of whether your OpenEdge application supports multi-tenancy, the multi-domain capability is still available for use. In many OpenEdge applications, the use of OpenEdge domains is simply transparent, and you may choose later how they can be employed to enhance security in your OpenEdge application.

Because support for OpenEdge domains is always present and used, the process of making the transition to one of the SaaS multi-tenancy models, or to a multiple domain security architecture, is made easier because you are able to add and configure OpenEdge domains in the OpenEdge components that require them. The goal of this document is to provide you with a basic understanding of OpenEdge security domains and how they work so that you can use them effectively within your OpenEdge application.

How OpenEdge security domains work

Every OpenEdge domain has two major attributes: a name, and an access code. The domain name is something you choose that is short but meaningful within your OpenEdge application. The access code is a shared secret that permits a CLIENT-PRINCIPAL token to be identified as representing a user of a single OpenEdge domain and therefore able to access the domain’s components. When a CLIENT-PRINCIPAL token is presented by a client, its domain name is used by the component’s authorization process to first look up the domain’s configuration in the component’s domain registry. If the domain configuration can be found, and its access code can be used to validate the CLIENT-PRINCIPAL security token, the component will permit access to the user represented by that CLIENT-PRINCIPAL token.

Therefore, accessing a domain component’s function and data requires a CLIENT-PRINCIPAL token that can be validated by the OpenEdge component. Consequently, the user who wants access to the OpenEdge domain must first obtain a CLIENT-PRINCIPAL token by authenticating to one of the domain component’s trusted authentication systems. Those domain component authentication systems validate user IDs and passwords that are located in secured and trusted locations. When the user account validation is successful, the client is issued a CLIENT-PRINCIPAL token that is sealed with the domain’s access code, which makes the CLIENT-PRINCIPAL token usable only in a single OpenEdge domain. Alternately, when a client presents the domain component’s authentication system with a non-OpenEdge security token, the authentication system will validate it using keys obtained from the token’s source and the tokens expiration date. If that validation is successful, that token is then reissued as a sealed CLIENT-PRINCIPAL token in the same way as the authentication of a user ID and password.

After a CLIENT-PRINCIPAL token is obtained for an OpenEdge domain, the token may be used to access any OpenEdge component that is a member of that user’s domain.

Architecture of a security domain configuration

After you understand the basics of how OpenEdge domains operate, the next step is to understand how an OpenEdge component becomes added or removed as member of a domain. OpenEdge components become members of a domain when you add a domain’s configuration to the component, and are removed from a domain when you remove that domain’s configuration. To enable support for multiple multi-tenant architecture models or security domains in existing OpenEdge applications, you may choose to isolate a single component to a single OpenEdge domain, or permit a single component to be a member of multiple domains. You accomplish that by managing the OpenEdge domain configurations in each OpenEdge component.

An OpenEdge security domain configuration applies to a single domain name and contains properties that are used by the component’s authentication and authorization processes when operating in that domain. To continue support of OpenEdge products operating as standalone components, each member of an OpenEdge domain can individually be configured to be an authentication point that produces CLIENT-PRINCIPAL tokens for a domain, or an authorization point that controls user access based on a CLIENT-PRINCIPAL token’s domain, or both.



OpenEdge has three separate architectures for storing a security domain configuration: one for a PAS for OpenEdge ABL application, one for OpenEdge Database, and another for OpenEdge Authentication Gateway. The main differences among these architectures is in how the domain configuration data is stored for use by the component's authentication or authorization processes, as follows:

  • In OpenEdge Authentication Gateway, the security domain configurations control the authentication processes and specify which source of user accounts are used to authenticate a user to a domain and subsequently produce CLIENT-PRINCIPAL tokens for that domain. The domain configuration is split between a JSON storage file for non-sensitive domain properties, and an encrypted keystore for the sensitive domain properties. The OpenEdge Authentication Gateway authorization process, when enabled, also uses the domain configuration to isolate the OpenEdge installations that may access it and receive CLIENT-PRINCIPAL tokens.
  • In a PAS for OpenEdge ABL application, the default authentication process operates using a single security domain configuration that specifies the source of user accounts that is used to validate user IDs and passwords. If the validation is successful, the domain configuration is used to control the creation of CLIENT-PRINCIPAL tokens that the user may use to access other members of its domain. The security domain configurations are also used in the ABL web application's authorization process to validate CLIENT-PRINCIPAL tokens that are passed by its clients before they are granted access to the application’s functions and data. The domain configuration data is split between property files that hold non-sensitive properties, and an encrypted keystore for the sensitive domain properties.
  • In OpenEdge Database, the security domain configurations are used in the authentication process to control the user account sources that may be used to validate a user’s ID and password, and subsequently the creation of a sealed CLIENT-PRINCIPAL token. The security domain configuration is also used by the database authorization process to validate a client-asserted CLIENT-PRINCIPAL token before granting the user permission to use the database. This is especially the case where the database is enabled for multi-tenancy and each OpenEdge domain represents one tenant. The domain name (also known as the tenant name) is used to physically isolate tenant-accessible data from users in any other tenant domain. The domain configuration data is contained in restricted access database tables whose fields contain clear-text non-sensitive data and encrypted sensitive data.

Despite these architectural differences, the primary function of a security domain is consistent across the suite of OpenEdge products: to trust a common security token for authentication and authorization. However, the way in which domain configurations are specified and stored is contextual to each product. Therefore, the process of setting up and storing a security domain configuration depends on the OpenEdge product you are configuring.

Components of a security domain configuration

All OpenEdge security domain configurations are stored in the component's domain registry and have a common set of properties that are used by its authentication and authorization processes:

  • Domain name—An OpenEdge domain is identified by a name that is unique across the application for all domains.
  • Domain access code—A secret value used by OpenEdge to cryptographically seal a security token during user authentication and to validate a user's sealed security token. For example, to assert their identity in a single sign-on (SSO) operation. When specified, this is typically an encrypted value that is contained in a long character string whose encryption key is known only by OpenEdge.
    Note: This is not a user account password and should not be used as such.
  • Enablement indicator—Specifies whether the domain is enabled for use at run time (the default). For example, the indicator allows you to configure domains for deployment while not making them available to an OpenEdge application until its deployment is complete.

Depending on the OpenEdge component, security domain configurations may also include the following types of properties for controlling the resource’s authentication process:

  • The authentication system type—The type of authentication system that the domain relies on for authenticating the user ID and password of all users of that domain; for example, the local operating system user accounts, or those stored in Microsoft Active Directory. OpenEdge supports several built-in authentication system types and allows you to define new ones, including ones that allow you to define your own authentication system. Each type of authentication system supports a particular set of user accounts and specific operations to validate and set a given user identity.
  • A tenant name—For a multi-tenant database component, this property identifies the physical tenant to which the domain belongs, and through which all users in the domain have access to the tenant's data. For a non-multi-tenant database, this setting is ignored.
  • System options—Allows you to specify options that can be used by the component's authentication process to connect to, and interoperate with, the authentication system type. Therefore the system options content is contextual to the authentication system type.
  • Additional settings—To support auditing and other options that currently have limited or no effect on user validation.
  • CLIENT-PRINCIPAL settings—Optional properties that provide fine-grained control of CLIENT-PRINCIPAL attributes in some components.


OpenEdge products that support security domains

Any OpenEdge component that authenticates and authorizes access requires a minimum of one security domain configuration. These products include the following:

  • OpenEdge Database and select database utilities
  • SQL-92
  • PAS for OpenEdge
  • OpenEdge Authentication Gateway

In brief, anywhere in OpenEdge where you can seal a CLIENT-PRINCIPAL token, and anywhere where you can validate a CLIENT-PRINCIPAL seal, must have a security domain registry.

Default domain configurations and the blank domain

Each OpenEdge product whose authentication or authorization processes support using OpenEdge domains that requires a domain configuration will include a default OpenEdge domain configuration that is automatically set up during installation. This default configuration enables OpenEdge to work out-of-the-box and is suitable for quickly setting up an application environment in which the security requirements involve only a single group of users.

This default security domain is commonly referred to as the blank domain, and is used whenever a user’s ID does not contain a specific domain that is qualified in the form of @domain-name. Included in the default blank security domain configuration is a default domain access code (""). The blank domain name is specified within a security domain configuration within two consecutive double-quote characters (""). Anytime a domain name is not a blank string, it is referred to as a named domain. The effect of using the blank domain is that all installed OpenEdge components will operate in a single domain, where any component may authenticate a user, obtain a CLIENT-PRINCIPAL token for the blank domain, and use that CLIENT-PRINCIPAL token to access any other OpenEdge component in that blank domain.

The default blank domain has a domain configuration like any named domain you may define. The blank domain operates the same way as named domains and may be disabled, its authentication system type changed, and its access code changed.

For example, the following code snippet shows the default domain configuration file that is provided with OpenEdge Authentication Gateway:



Notice the name attribute, which specifies the domain name, and that it contains a blank value. Note that the domain configuration does not have an access code field. In OpenEdge, all domain access codes are stored in an encrypted form, which for the Authentication Gateway is an encrypted Java keystore file whose default name is domains.keystore.

In PAS for OpenEdge ABL application domain configurations, the domain access codes are also stored in an encrypted Java keystore file, using the default name ABLDomainRegistry.keystore, which is found in the conf/ directory of that PAS for OpenEdge ABL application instance.

The security domain configurations for OpenEdge Database are stored in two related tables. The domain access code is, in this case, stored as an encrypted value in one of the table fields.

When you set up OpenEdge to permit a user's access to multiple domains, you must specify full domain names in the user ID within domain configurations that are used to authenticate the user to the domain. The resulting CLIENT-PRINCIPAL token then includes the user’s domain name so that it can be used to access components of that single domain.

Domain names and multi-tenancy

As stated previously, OpenEdge security domains came into being to support multi-tenancy across the OpenEdge products. One default blank domain is preconfigured in domain-enabled OpenEdge products in preparation for moving to more complex security architectures, such as multi-tenancy. When you are preparing for multi-tenancy, it is a good idea to create a sustainable naming convention for OpenEdge domains. Although you can choose any naming convention for your tenant-related OpenEdge domain names that suite your application, consider the following example to illustrate the options that are available to you.

As we know, businesses often change their names. They are also frequently subsumed by other businesses, and they are sometimes rendered inert as they realign their finances. The domain and tenant naming separation may help you with those business changes and transitions.

For example, a tenant’s legal name is Acme General Products Corp and uses acmeprods.com as their internet domain name. You can expect tenant users to continue logging in using their internet domain names, and they can do that by using it by making their OpenEdge domain names be the same. But consider what happens when Acme General Products Corp changes its name to Eastern Business Machines LLC and begins using the internet domain easternbp.com. Because of the separation between a tenant that is stored in an OpenEdge Database instance and the OpenEdge domain names, the employees can continue to log in using the acmeprods.com OpenEdge domain name to access their tenant data. Later, you can add a new OpenEdge domain easternbp.com that maps to the same tenant data as the previous acmeprods.com did. After users are logging in using the new OpenEdge domain name, the previous OpenEdge domain name can be removed without interruption in tenant access. The same type of process can occur when one business buys another. Although this is a very simple scenario, it serves as an illustration of what is possible when you have the ability to use multiple OpenEdge domain names to access a single tenant organization’s data.

In general, however, security domain names can be anything you want, provided that the name is unique and has a unique domain access code. You might find it useful to compose a domain name as a combination of the business name and the application name. That way, the domain name scheme can provide separation between the users of a given application who are associated with one company and the users of that application from a different company.

Domain access codes

In each OpenEdge domain configuration, every security domain name must have a corresponding domain access code. As mentioned earlier, a domain access code is a shared secret value used by OpenEdge to cryptographically seal a security token during user authentication and to validate a user's sealed security token. If your OpenEdge environment contains two or more domain configurations—for example, one for a tenant named acme.com, and another for a tenant named greatreads.com—the domain access code for a given security domain name must be the same in each domain component's configuration in order to permit access.

For example, to sign and validate the CLIENT-PRINCIPAL token that is created for jane@acme.com and that is used in both PAS for OpenEdge and OpenEdge Authentication Gateway components, the domain configurations for those two OpenEdge products must have the same domain access code for acme.com.

For multiple domain's security to operate effectively, each domain should have a unique access code. How that uniqueness appears in your OpenEdge application is best implemented as a design of the application and its configuration maintenance.

When you use the default blank domain, its access code is suitable for development operations because you can develop and unit-test your OpenEdge application to use CLIENT-PRINCIPAL tokens as an enabler to employ multiple domains without having to define and maintain multiple domains. However, when you move an OpenEdge deployment into a production environment, you should never retain the default blank domain’s access code and should change it in every OpenEdge component where the default blank domain is configured the same way that any named domain’s access code would be maintained.

Authentication system types

As mentioned earlier, a domain configuration controls the authentication processes. However, OpenEdge products cannot all use the same authentication process implementation, and this is reflected in the types of authentication system types that the components can use. OpenEdge supports the following authentication system types:

  • _oeusertable—Built-in system that authenticates against the _User table accounts, and is supported for OpenEdge databases.
  • _oslocal—Built-in system that authenticates against the local operating system user accounts on the system where the authentication process runs. This system type is available in OpenEdge Database and Authentication Gateway.
  • _extsso—Built-in system that relies on callbacks into an ABL application to do user authentication, and is supported for OpenEdge databases.
  • properties : local—Built-in system that authenticates user IDs and passwords against a simple text file. This system type is available in PAS for OpenEdge ABL applications and the OpenEdge Authentication Gateway for use in product development environments.
  • sts—Built-in system that delegates a PAS for OpenEdge ABL application or OpenEdge Database’s user authentication process to use OpenEdge Authentication Gateway to authenticate domain users and produce CLIENT-PRINCIPAL tokens.
  • LDAP : Active Directory—Built-in system that authenticates users to a Directory Service account. This system type is available for the PAS for OpenEdge ABL application and OpenEdge Authentication Gateway.
  • OAuth2 : JWT—Built-in system that is used to validate client-supplied non-OpenEdge security tokens and produce an equivalent CLIENT-PRINCIPAL token. This system type is available in the PAS for OpenEdge ABL application.
  • SAML—Built-in system that is used to validate client supplied non-OpenEdge security tokens and produce an equivalent CLIENT-PRINCIPAL token. This system type is available in the PAS for OpenEdge ABL application.
  • OERealm—Built-in system that enables a PAS for OpenEdge ABL application or OpenEdge Authentication Gateway authentication processes to call developer-written ABL code that interfaces with external user account systems that are not in OpenEdge’s list of built-in Authentication system types. The OERealm does not actually authenticate the user, but does perform the tasks of looking up the user account, validating the account’s password, and supplying account information that is folded into the generation of a CLIENT-PRINCIPAL token.

Where and how these authentication types are specified is contextual to the OpenEdge product. For example, in OpenEdge Authentication Gateway, you identify the authentication system type by specifying the authProvider property in the domains.json file. In OpenEdge Database, you use the Data Administration tool. In PAS for OpenEdge ABL applications, you use the oeablSecurity.properties file.

The default blank domain includes configuration properties for designating a default authentication system type. The choice of authentication system type is consistent with the type of OpenEdge component and its ability to be a standalone component that is capable of both authenticating users and to granting them access to itself. Those default authentication system types are:

  • OpenEdge Database (including ABL and SQL-92 clients)—The _oeuser table
  • PAS for OpenEdge ABL application—The user.properties text file
  • OpenEdge Authentication Gateway—The user.properties text file

Those default authentication system types are chosen specifically to make it easier for developers to use, but you may change them to another type as necessary. Normally, these authentication system types are recommended to be used only in development environments because they do not support the level of user-account security necessary for production systems. You may continue to use the default blank domain, but you should change the authentication system type before you use it in a production deployment.

For more information, see Defining and specifying the system type.