The domains.json configuration file contains the event callback policies. The following is a sample event configuration file containing a single event callback configuration named login, implemented by the SampleEventHandler class. Event handler classes must implement OpenEdge.Security.STS.IEventProvider.

    "version": "1.0.0",
    "domains": [
        {
        "name" : "local",
        "enabled" : true,
        "description" : "O/S Authentication",
        "actions" : {
            "authenticate" : {
                "enabled" : true,
                "options" : ""
. . .
        },
        "options" : "-processid",
        "authProvider" : "_oslocal",
        "policyProvider" : "",                                                              
        "events" : {
            "provider" : "login",                                                  
            "groups" : {
               "tokenAuthenticate" : true,
               	"tokenExchange" : true
}
        }
    },

. . .

"eventProviders" : {
    "local" : {
        "type" : "com.progress.sts.SampleEventHandler",
        "hash" : ""
    }
},

The eventProvider object defines one or more event handlers, where each event handler is required to provide "type"and optionally a "hash”. Event groups encapsulate one or more individual process events which may be intercepted and interpreted by the Event: Provider ABL class.

In the above code example, the bold lines:
  • "events":{"provider" : "login"—References the eventProvider to be called when the group action happens in the domain.
  • "tokenAuthenticate" : true, "tokenExchange" : true—The events that will cause the eventProvider to run the appropriate code.
    • tokenAuthenticate and tokenExchange groups—Enable and disable the OpenEdge Authentication Gateways publishing authenticate/exchange process events to the OpenEdge Domains' configured Event: Providers.
  • "local" : {"type" : "com.progress.sts.SampleEventHandler", "hash" : "" — This is the event run for the "local"domain when tokenAuthenticate/Exchange happens.
    • "type"— A fully-qualified ABL class name to which the process events are published.
    • "hash"— Optional field ensures that published events only go to a specific ABL class object. The value is obtained from RCODE-INFO and converted to a text value.

The following is a sample event handler class that prints messages to the log file.

SampleEventHandler.cls

using Progress.Lang.*.
using OpenEdge.Security.STS.IEventProvider.
using OpenEdge.Security.Principal.
using Progress.Json.ObjectModel.JsonObject.
block-level on error undo, throw.
class com.progress.sts.SampleEventHandler implements IEventProvider:
    method public void RecordEvent( input pcSender as character,
                                input pcEvent as character,
                                input poPrincipal as Principal,
                                input poDomainCtx as JsonObject ):
    message "sender:" pcSender skip
    "event:" pcEvent skip
    "C-P Token" poPrincipal:Token skip
    "context:" poDomainCtx.
    end method.
end class.
Note: For a practical example of adding events, see Add auditing to the OpenEdge Authentication Gateway server.

Data integrity signature-value for events and policies

The data integrity signature-value in the code examples is a security feature to make sure the correct code is being run. If the data integrity signature-value doesn’t match, it may mean the code was replaced, and the code will not run. This protects from someone changing the policy code, and possibly changing the client-principal, or dumping private information in the log file during an event.

Follow these steps to use the "hash"value protection:

  1. Compile the code, for example:
    COMPILE SimpleEventHandler.cls SAVE.
  2. Get the data integrity signature-value from the compiled code, for example:
    RCODE-INFO:FILE-NAME = "SimpleEventHandler.r".
DISPLAY RCODE-INFO:SIGNATURE-VALUE FORMAT "x(60)".
  3. Deploy the r-code only to the Authentication Server’s PROPATH.
  4. Add the data integrity value to the domains.json file, for example:
    "eventProviders" : {
    "local" : {
        "type" : "com.progress.sts.SampleEventHandler",
        "hash" : "xZ89gQ4apaZ79dR8s+qK5YjbB8f1X0t/4+gSfZ41/1U="
    }
},