Security event logging
In addition to data and rule modification auditing and recording work history, Pega provides the ability to record security-related events to a file named PegaRULES-SecurityEvent.log. You can access this log file from Dev Studio by clicking Configure > System > Operations > Logs > Log files.
The following items are examples of security event log entries. Notice that each entry is recorded using JSON format.
{"id":"6e11a563-fd93-46d8-9de0-3963fb43a70f","eventCategory":"Security administration event","eventType":"security event configuration changed","appName":"Booking","tenantID":"shared","ipAddress":"192.168.118.1","timeStamp":"Fri 2019 Jul 12, 17:30:54:274","operatorID":"Admin@Booking","nodeID":"ff9ef7835fd4906aea82694c981938d0","message":"security event configuration has been modified.","requestorIdentity":"20190710T213105"}
{"id":"ed76e8a7-ea28-4e9a-8830-01e8e90301ae","eventCategory":"Authentication event","eventType":"Operator record change","appName":"Booking","tenantID":"shared","ipAddress":"192.168.118.1","timeStamp":"Fri 2019 Jul 12, 17:41:24:976","operatorID":"Admin@Booking","nodeID":"ff9ef7835fd4906aea82694c981938d0","requestorIdentity":"20190710T213105","operatorRecID":"DATA-ADMIN-OPERATOR-ID ADMIN@BOOKING","operatorRecName":"Admin","operation":"update"}
{"id":"ed76e8a7-ea28-4e9a-8830-01e8e90301ae","eventCategory":"Authentication event","eventType":"Operator record change","appName":"Booking","tenantID":"shared","ipAddress":"192.168.118.1","timeStamp":"Fri 2019 Jul 12, 17:41:24:976","operatorID":"Admin@Booking","nodeID":"ff9ef7835fd4906aea82694c981938d0","requestorIdentity":"20190710T213105","operatorRecID":"DATA-ADMIN-OPERATOR-ID ADMIN@BOOKING","operatorRecName":"Admin","operation":"update"}
Clicking Configure > Org & Security > Tools > Security > Security Event Configuration displays which type of events are recorded. Then, you can enable or disable Custom event logging.
Note: The Security Event Configuration allows you to turn only custom events on or off.
Security event configuration setting does not provide control over when individual custom events are logged. For example, you can define a parameterized When rule used to control whether a step in a data transform or activity step records a custom security event. The When rule parameter can be used to perform a data page-mediated lookup to see whether logging of the custom event has been enabled.
Custom event logging can be used to facilitate the fulfillment of client-based access control (CBAC) auditing requirements.
It is possible to log a custom event within an activity Java step by using:
tools.getSecEventLogger().logCustomEvent(PublicAPI tools, String eventType, String outcome, String message, Map<String, String> customFlds)
Use one of the following parameter values:
- eventType: Name of the event type to keep track of custom events
- outcome: The outcome of the event
- message: Any message that a user needs to log as part of the event.
- customFlds: A map of key-value pairs that log extra information for the event.
However, a better long-term approach is to execute this API with a Rule-Utility-Function as future versions of Pega Platform™ may curtail the use of Java steps in activities.
The Pega Community topic Adding a custom security event explains how to record a custom security event by creating a Java step within an activity.
It is overly complex to require code that calls a function to supply a StringMap (Map<String, String>) customFlds parameter. The function can instead accept a text-based ValueGroup property. That ValueGroup property can be converted to a StringMap within the function. The following steps describe how you configure this function.
- Create a library and function.
- Have the function accept four parameters (String, String, String, ClipboardProperty).
- Make the supplied ClipboardProperty a ValueGroup.
The function converts the ValueGroup ClipboardProperty to a locally declared Map<String, String> customFlds variable.
PublicAPI tools = null;
PRThread thisThread = (PRThread)ThreadContainer.get();
if (thisThread != null) tools = thisThread.getPublicAPI();
else throw new PRAppRuntimeException("Pega-RULES", 0, "Unable to obtain current thread");
Map<String, String> customFldsMap = new HashMap<String, String>();
java.util.Iterator iter = customFlds.iterator();
while (iter.hasNext())
{ ClipboardProperty prop = (ClipboardProperty)iter.next();
customFldsMap.put(prop.getName(), prop.getStringValue());
}
tools.getSecEventLogger().logCustomEvent(tools, eventType, outcome, message, customFldsMap);
PRThread thisThread = (PRThread)ThreadContainer.get();
if (thisThread != null) tools = thisThread.getPublicAPI();
else throw new PRAppRuntimeException("Pega-RULES", 0, "Unable to obtain current thread");
Map<String, String> customFldsMap = new HashMap<String, String>();
java.util.Iterator iter = customFlds.iterator();
while (iter.hasNext())
{ ClipboardProperty prop = (ClipboardProperty)iter.next();
customFldsMap.put(prop.getName(), prop.getStringValue());
}
tools.getSecEventLogger().logCustomEvent(tools, eventType, outcome, message, customFldsMap);
The following code is an example of a custom security event.
{"id":"c86a4299-9355-418b-b95d-519f842693d1","eventCategory":"Custom event","eventType":"FooBla","appName":"Booking","tenantID":"shared","ipAddress":"192.168.118.1", "timeStamp":"Fri 2019 Jul 12, 17:46:05:284","operatorID":"Admin@Booking", "nodeID":"ff9ef7835fd4906aea82694c981938d0","outcome":"Fail","message":"FooBla failed","requestorIdentity":"20190710T213105"}
Note: The event category for every custom security event is Custom Event. To enable or disable logging of a specific custom security event type, you need to use the (custom) eventType value as a When rule parameter. The When rule uses the parameter to perform a node-level data page lookup. If the lookup shows that logging of the custom eventType is enabled, the When rule returns true. In turn, the custom security event-logging function (RUF) is called.
This Topic is available in the following Module:
If you are having problems with your training, please review the Pega Academy Support FAQs.
Want to help us improve this content?