A minimal Authentication Gateway configuration requires at least one domain entry. Without domain configuration information, the OESTS implementation will not work. Other domains may be provided, and optionally, ABL policy and event callback handlers may also be defined.

Domain configuration files

Domain configurations are stored in instance-name/webapps/ROOT/WEB-INF/config/domains.json, where instance-name is the name of the OpenEdge Authentication Gateway instance where your OESTS web application is deployed. This is a simple JSON-formatted text file that can be edited to define domain entries.

Note: Alternatively, you can export domains by dump_domains.p as described in Data export utility.

Additionally there is a instance-name/webapps/ROOT/WEB-INF/config/domains.keystore file. This is a Java KeyStore (PKCS12) type file that holds the domain access codes for the configured domains. For more information, see Configure domain access codes.

The domains.json file

The default domains.json file contains the blank ("") domain configured for authentication and oests.server, which is disabled by default. You will need to provide any additional domains required in your environment.

The default blank domain is configured to use a property file as the authentication mechanism. This file is stored in instance-name/webapps/ROOT/WEB-INF/config/users.properties. This default domain configuration is simplified intentionally to make initial development easier, but using the blank domain at later stages is not recommended, especially in a multi-domain environment.

A domain configuration defines the authentication provider to be used for login (see Spring Security Configuration for more information), the ABL policy for the domain, the event handler implementation, as well as additional context information that can be used by policy and event callback handlers.

The following is a sample domains.json file that defines a single domain given a blank domain name. The domain is enabled and is marked as supporting both Single Sign On (SSO), and login (authenticate) operations. The last required entry is the name of the authentication provider implementation. In this case, it is named properties. The properties authentication provider is configured to use a users.properties file with a couple of simple default user/password combinations for testing purposes.

domains.json

{
    "version": "1.0.0",
    "domains": [
    	{
    	"name" : "",
        "enabled" : true,
        "description" : "Default domain",
        "actions" : {
            "authenticate" : {
            	"enabled" : true,
            	"options" : ""
            },
            "exchange" : {
            	"enabled" : false,
            	"options" : ""
            },
            "sso" : {
            	"enabled" : true,
            	"options" : ""
            },
            "refresh" : {
            	"enabled" : false,
            	"options" : ""
            }
       },
       "options" : "",
       "authProvider" : "properties",
       "policyProvider" : "",
       "events" : {
            "provider" : "",
            "groups" : {
                "client" : false,
                "tokenAuthenticate" : false,
                "tokenExchange" : false,
                "tokenRevoke" : false,
                "tokenValidate" : false,
                "tokenRefresh" : false,
                "policy" : false,
                "sessionLogin" : false,
                "sessionLogout" : false,
                "sessionValidate" : false,
                "sessionRefresh" : false
            }
       }
    },
    {
    	"name" : "oests.server",
        "enabled" : false,
        "description" : "STS server key domain",
        "actions" : {
            "authenticate" : {
            	"enabled" : false,
            	"options" : ""
            },
            "exchange" : {
            	"enabled" : false,
            	"options" : ""
            },
            "sso" : {
            	"enabled" : true,
            	"options" : ""
            },
            "refresh" : {
            	"enabled" : false,
            	"options" : ""
            }
        },
        "options" : "",
        "authProvider" : "anonymous",
        "policyProvider" : "",
        "events" : {
            "provider" : "",
            "groups" : {}
        }
    }],
    "policyProviders" : {
    
    },
    "eventProviders" : {
    
    }
}

Configuration file monitoring

The domains.json, domains.keystore, and users.properties configuration files are actively monitored for changes by the OESTS application. If a change is made to one of these files, the changes will be applied without restarting the OESTS application. The files are read at startup of the OESTS web application and again after the files have changed.

Configuration file location

You can change the location and name of the OESTS configuration files by editing sts.properties file. This file is stored in instance/webapps/ROOT/WEB-INF/config. By default, configuration files are referenced as relative file paths from the web application. Edits to sts.properties require a restart of the OESTS web application or the Authentication Gateway itself.

Domain object properties

The configurable domain properties include: 

    "domains": [
                    ...
                    {
                    "name" : "sample.com",
                    "enabled" : true,
                    "description" : "A sample domain for demonstration purposes",
                    "actions" : {
                    "authenticate" : {
                    "enabled" : true,
                    "options" : ""
                    },
                    "exchange" : {
                    "enabled" : false,
                    "options" : ""
                    }
                    },
                    "options" : "",
                    "authProvider" : "properties",
                    "policyProvider" : "",
                    "events" : {
                    ...
                    }
                    }
                    }
All properties are mandatory unless explicitly marked optional.
Where:
  • name: Specifies the domain name.
  • enabled: Enables the domain.
  • description: (Optional) Identifies the purpose of the domain.
  • actions: Specifies one of the following objects:
    • authenticate Validates user credentials, userid and password, using the authProvider and returns either an id or access token.
    • exchange Exchanges an input id token issued by either an external OE AVM or another identity provider and returns an access token.
  • options (Optional) Adds custom behavior.
  • authProvider: Specifies the components that support the validation of user credentials and provide certain information, such as roles, relating to the user. A single authentication provider can support many domains. The supported authProviders include:
    authProvider Options User account location
    ad Not available Uses AD user object’s userPrincipalName attribute.
    ldap Not available Uses LDAP user account object's attribute(s).
    oerealm Not available Uses the configured OERealm's HybridRealm ABL interface, this is open to any 3rd party user account storage accessible via a shared OS library.
    _oeusertable Not available Uses the configured OERealm's HybridRealm ABL interface, which OE ABL database, table, and field(s).
    _oslocal 
    authentication | exchange: "-processid"
    Uses one of the following:
    • Authentication uses any user account accessible via OpenEdge Authentication Gateway OS system libraries
    • exchange uses any user account permitted to log into the server or workstation who connects to an OpenEdge ABL database.
    properties Not available Uses the STS (aka ROOT) web application’s WEB-INF/config/users.properties file.
  • policyProvider: (Optional) ABL components allow the service to apply policies in addition to any provided by the authentication providers. For example, this includes changing credentials' expiry dates or preventing login at certain times. Policies are provided by optionally modifying and returning a client-principal.
  • events (Optional)
    • provider ABL components that allow the service to observe and act on predefined events as they occur in the authentication process. These are configured per-domain and are for observational purposes, like logging or auditing.
    • groups The following groups are used.
      Event Group Event Description
      client CLIENT-AUTHENTICATING Adds auditing for client-authenticating events.
      CLIENT-AUTHENTICATED Adds auditing for client-authenticated events.
      CLIENT-AUTHENTICATION-ERROR Adds auditing for client-authentication-error events.
      tokenExchange TOKEN-EXCHANGING Adds auditing for token-exchanging events.
      TOKEN-EXCHANGE-ERROR Adds auditing for token-exchange-error events.
      TOKEN-EXCHANGED Adds auditing for token-exchanged events.
      policy POLICY-APPLYING Adds auditing for policy-applying events.
      POLICY-APPLICATION-ERROR Adds auditing for policy-application-error events.
      POLICY-APPLIED Adds auditing for policy-applied events.
      For examples, see Add policies to the OpenEdge Authentication Gateway server, Configure event callbacks, and Add policies to the OpenEdge Authentication Gateway server.