Any location in your OpenEdge application architecture where a user can be authenticated, or where a CLIENT-PRINCIPAL token can be validated, is called a point of authentication. In the OpenEdge environment, each point of authentication must have a minimum of one security domain configuration. Consequently, each source of user identity information that is used in that point of authentication must be specified within a domain configuration. How many domains your OpenEdge environment must have, and understanding where all the points of authentication are, is central to creating a security domain architecture for your environment that can be easily scaled or modified as your requirements change.

Basic security domain scenario with single PAS for OpenEdge ABL application

The following figure shows a basic OpenEdge environment that uses a single security domain that is configured in a domain registry for a PAS for OpenEdge ABL application.



When the OpenEdge client user performs a direct login to invoke a service hosted in the PAS for OpenEdge ABL application, the embedded Spring Security Framework authenticates the client by using the domain configuration to know where and how to look up the user's credentials in an identity store. The identity store can be an LDAP server, such as Microsoft Active Directory, or the local operating system that is located on a network-connected OpenEdge Authentication Gateway instance, for example. If the user can be authenticated (that is, the user account is found, is enabled for use, and its password validates):

  1. Spring uses the domain configuration to assign an OpenEdge domain name, if the input user ID does not contain one. That fully qualified user ID is then used throughout the remainder of the authentication process. You may retain the use of the default blank domain, but you can configure another.
  2. Spring uses the single authentication system configuration for all user logins and interacts with it to validate the user ID account, its enabled state, its expiration, and its password value.
  3. Spring generates an internal token for the user, which contains the user and optionally the user account's data. That is, the user name, roles, and domain.
  4. PAS for OpenEdge converts the Spring token into a CLIENT-PRINCIPAL object using the CLIENT-PRINCIPAL generation properties located in the domain configuration.
  5. Spring then reads from the domain registry to determine whether the user's domain to be recorded in the CLIENT-PRINCIPAL object is listed in the domain registry, and that the domain is enabled. If there is a match, the user's CLIENT-PRINCIPAL token is sealed and access to the service is allowed, otherwise access is denied because the component is not configured as a member of the domain.
  6. The CLIENT-PRINCIPAL token is then delivered to the ABL business application code on this and every subsequent request.
  7. The business application code can use the CLIENT-PRINCIPAL token to access the OpenEdge database, if that database’s domain configuration includes the user’s domain name and the token can be validated using the domain’s access code.

When the PAS for OpenEdge ABL application is configured to use an OpenEdge Authentication Gateway instance, it attains the ability to handle user authentication for multiple domains, each with its own authentication system configuration.

In the case where a non-OpenEdge-issued single sign-on token is presented to PAS for OpenEdge:

  1. Spring Security validates the external token using keys that Spring obtains from the issuer of that token.
  2. PAS for OpenEdge assigns the token’s user to an OpenEdge domain and then converts the token into a CLIENT-PRINCIPAL object according to the CLIENT-PRINCIPAL generation properties found in the domain configuration.
  3. Spring reads from the domain registry to determine whether there is a match with the domain in the CLIENT-PRINCIPAL object. As with direct login, access is permitted depending on whether there is a match with a domain that the component is a member of.
  4. The CLIENT-PRINCIPAL token is then delivered to the ABL business application code on this and every subsequent request.

Basic security domain scenario with OpenEdge Database

The following figure shows OpenEdge Database with an ABL client, a SQL-92 client, and a SQL-92 Server client. The ABL and SQL-92 Server clients are configured with a pluggable authentication module (PAM), which reads domain registry information that is stored in OpenEdge Database.



In OpenEdge Database, the domain registry is made up of two database tables. One is the domain table, which lists all the domains from which access is permitted, and the other table specifies the authentication systems that can be used for clients that create a database connection. Together these tables specify to the PAM for each client which identity store to use.

The authentication process that is used depends on the client type, as follows.

ABL client

  1. The PAM authentication process assigns the default blank domain to the user ID if the input user ID does not contain one. That fully qualified user ID is then used through the rest of the authentication process.
  2. The PAM reads the domain configuration records from OpenEdge Database and uses the authentication system configuration for the user ID’s domain and interacts with it to validate the user ID account, its enabled state, its expiration, and its password value. If the domain is not configured or is disabled, the authentication attempt is rejected.
  3. The PAM generates an internal token for the user, which contains the full user specification and optionally the user account’s data. That is, the user name, domain, and optionally other user account information.
  4. The PAM converts the token into a CLIENT-PRINCIPAL token.
  5. The PAM seals the user’s CLIENT-PRINCIPAL token using the domain-configured access code and stores it in the database connection.
  6. The CLIENT-PRINCIPAL token is then made available to the ABL business application that can use it to access other OpenEdge databases or PAS for OpenEdge ABL applications.

When the PAS for OpenEdge ABL application is configured to use an OpenEdge Authentication Gateway instance, the ABL application attains the ability to handle user authentication for multiple domains, each with its own authentication system configuration.

In the case where an OpenEdge CLIENT-PRINCIPAL token is used to single sign-on to the database connection:

  1. Spring Security validates the external token using keys that are obtained from the issuer of that token.
  2. PAS for OpenEdge assigns the token’s user to an OpenEdge domain and then converts the token into a CLIENT-PRINCIPAL token according to the CLIENT-PRINCIPAL generation properties that are found in the domain configuration.
  3. Spring reads from the domain registry to determine whether there is a match with the domain in the CLIENT-PRINCIPAL object. As with direct login, access is permitted depending upon whether there is a match with a domain of which the component is a member.

The CLIENT-PRINCIPAL token is then delivered to the ABL business application code on this and every subsequent request.

SQL-92 client

The client login to SQL-92 follows the same direct-login process as described previously for the database’s ABL client. The difference is that:

  • The sealed CLIENT-PRINCIPAL token is not made available to the SQL-client where it can be used to access other SQL-92 databases.
  • The SQL-92 database connection will not accept a sealed CLIENT-PRINCIPAL token to gain access.

Basic security domain scenario with OpenEdge Authentication Gateway

You can configure OpenEdge Database or a PAS for OpenEdge ABL application to delegate its client authentication process to OpenEdge Authentication Gateway. In this scenario, when a client executes a direct login, the login operation is executed in the Authentication Gateway instead of locally. The SSO token authentication to these domain components remains local and continues to use the local OpenEdge domain registry configuration to reduce network overhead during peak operating times.

The Authentication Gateway exists as a single service for all PAS for OpenEdge and OpenEdge Database component instances in your application environment. It is fully multi-domain and multi-tenant enabled for direct user logins so that you maintain a single set of domain configurations in a secured server environment. The additional benefit that you derive from using the Authentication Gateway is that it permits you to supplement the provisioning and auditing of CLIENT-PRINCIPAL token generation using ABL. This single location of domain configuration and its security brings benefits to larger application environments and reduces maintaining many domain configurations in many locations.



In this configuration, whereby OpenEdge Database delegates the authentication process to OpenEdge Authentication Gateway, the PAM plug-ins used by the ABL and SQL-92 Server clients are substituted by an STS client plug-in, which is configured in OpenEdge Database. Whereas the PAM plug-in reads domain information from the domain registry tables in OpenEdge Database, the STS client plug-in delegates domain validation and authentication to the Spring Security Framework, which is part of the STS service in Authentication Gateway. The specifics of the authentication process depend on the database client type.

The PAS for OpenEdge ABL application follows the same pattern as ABL and SQL clients.

ABL client

When a database client executes a CONNECT operation to the database, the database forwards the user ID and password, by means of the STS client plug-in, to the STS service's Spring Security Framework in the Authentication Gateway to perform a login. The domains.json file contains the information that tells the Spring Security Framework how to connect to the identity store; that is, the location and connection information for the identity store. The Spring Security Framework then compares the domain that is passed in with the user identity to the domains listed in the domain registry. If a match is not found, the authentication process stops and returns an invalid domain exception. Basically, if the domain in the user credentials cannot be found in the domain registry, then the Spring Security Framework cannot find the configuration for the identity store that would be needed to locate the user account. However, if there is a match between the domain in the user identity and the domain registry, the Spring Security Framework reads in the user account information for that user from the identity store. If the user can be successfully authenticated, the Spring Security Framework provisions a CLIENT-PRINCIPAL token, seals it, and returns it to the database.

When the database receives the CLIENT-PRINCIPAL token, the database then validates the domain in that token against the domains listed in its domains table. If the database can validate the CLIENT-PRINCIPAL token—that is, the domain access code that was used to seal the token matches the domain access code in the database's domain registry—then the database accepts the ABL client's connection and returns the CLIENT-PRINCIPAL token to that client. Note that the business application for that ABL client can extract that token from the database connection and pass it over to other application servers and database connections. After the application obtains the CLIENT-PRINCIPAL token, the application can use that token to connect to other PAS for OpenEdge instances and perform single sign-on in other locations in the OpenEdge environment rather than having to pass a user ID and password around that continually requires re-authentication. Passing CLIENT-PRINCIPAL tokens among components in this way also facilitates auditing: because the tokens come from a trusted source, they are more secure and easier to trace.

SQL-92 client

The SQL-92 database client follows exactly the same use pattern as the ABL client, with the difference being that the sealed CLIENT-PRINCIPAL token is not available to the SQL-92 client for use with other databases.