Authored By: Marty Solomon
Introduction
This document provides advice for users responsible for ensuring the ongoing security of their Pega applications. It focuses on the OAuth 2.0 events that are written to the security events log whenever an event occurs that concerns OAuth 2.0 processing, such as dynamic client registration and token revocation. This document also provides guidance for how to interpret the log's contents. For more information, see Security events log.
Note: All events are always enabled.
OAuth 2.0 Events
Fields common to all events
The following table lists the fields and their values that are the same for all OAuth 2.0 events.
| Field Name | Value/Description |
| eventCategory | “OAuth 2.0” |
| ipAddress | IP address where the request originated |
| nodeID | Node ID on which the request was processed |
| operatorID | Operator ID issuing the request |
| timestamp | Date and time of the request |
| appName | Name of application |
Invalid token requests
Advice
Monitor frequently for excessive requests using a particular client ID or originating from a particular IP address. Block the IP address if the requests are not recognized.
Event message fields
| Field Name | Value/Description |
| eventType | “Token endpoint invoked” |
| HTTP Status Code | “400” |
| client_id | Client ID specified in the request |
| message | “The request is missing a required parameter”
“Invalid value provided for code parameter” |
| outcome | “invalid_request”, “invalid_grant” |
Example 1
{"HTTP Status Code":"400","appName":"PegaRULES","client_id":"32538105954914023226","eventCategory":"OAuth 2.0","eventType":"Token endpoint invoked","id":"a844af32-dc51-440c-8a64-c273f8d92e0b","ipAddress":"10.233.66.0","message":"The request is missing a required parameter.","nodeID":"pega-web-68484dd67f-fdwxd","outcome":"invalid_request","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 21:42:12:908"}
Example 2
{"HTTP Status Code":"400","appName":"PegaRULES","client_id":"32538105954914023226","eventCategory":"OAuth 2.0","eventType":"Token endpoint invoked","id":"2395b9a5-a05a-47a9-9866-3de7a0ccc617","ipAddress":"10.233.64.0","message":"Invalid value provided for code parameter","nodeID":"pega-web-7654775556-br9n4","outcome":"invalid_grant","tenantID":"shared","timeStamp":"Tue 2021 Nov 16, 14:29:20:088"}
API requests with invalid client credentials
Advice
Monitor periodically.
Event message fields
| Field Name | Value/Description |
| eventType | “Token endpoint invoked” |
| Description | “Invalid client secret” |
| HTTP Status Code | “401” |
| client_id | OAuth 2.0 client ID used in the request |
| message | “Client authentication failed” |
| outcome | “invalid_client” |
Example
{"Description":"Invalid client secret","HTTP Status Code":"401","appName":"PegaRULES","client_id":"32538105954914023226","eventCategory":"OAuth 2.0","eventType":"Token endpoint invoked","id":"7c821a91-f9d0-4851-b2a6-79fb1e9f96e5","ipAddress":"10.233.68.0","message":"Client authentication failed ","nodeID":"pega-web-7654775556-br9n4","outcome":"invalid_client","tenantID":"shared","timeStamp":"Tue 2021 Nov 16, 19:36:23:110"}
Token revocation from Rest API
Advice
Monitor regularly to identify unexpected token revocation requests. Block requests from IP addresses if requests are unexpected.
Fields
| Field Name | Value/Description |
| eventType | “Revocation token endpoint invoked” |
| HTTP Status Code | “400” |
| message | “The server cannot process as it is malformed syntax” |
| client_id | “xyz” |
| outcome | “Bad Request” |
Example (failed token revocation request)
"HTTP Status Code":"400","appName":"PegaRULES","client_id":"xyz","eventCategory":"OAuth 2.0","eventType":"Revocation token endpoint invoked","id":"630a9001-8eb9-4641-9aa7-14ef137079ff","ipAddress":"10.233.66.0","message":"The server cannot process as it is malformed syntax","nodeID":"pega-web-68484dd67f-fdwxd","outcome":"Bad Request","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 18:51:59:315"}
Regeneration of client secret from rule form
The system logs this event whenever the Regenerate client secret button on the OAuth 2.0 Client Registration rule form is enabled.
Advice
Monitor periodically. If this event is observed but not expected, block access to the operator/IP address from which the request occurred.
Fields
| Field Name | Value/Description |
| HTTP Status Code | “201” |
| client_id | “Registered client ID” |
| eventType | “Done from client registration rule form” |
| message | “client secret regenerated successfully” |
| outcome | “status created” |
Example
{"HTTP Status Code":"201","appName":"PegaDevelopment","client_id":"50595752443336245654","eventCategory":"OAuth 2.0","eventType":"Done from client registration rule form","id":"6f62ed9d-2dc5-48ad-8b4c-2ef1b9ada1f4","ipAddress":"10.233.67.0","message":"client secret regenerated successfully","nodeID":"pega-web-68484dd67f-fdwxd","operatorID":"xyz","outcome":"status created","requestorIdentity":"20170317T160417","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 19:20:35:481"}
Token revocation from rule form
Advice
Monitor daily. Ensure all entries are legitimate requests for token revocation. Block requests from IP addresses for unexpected revocation requests.
Fields
| Field Name | Value/Description |
| HTTP Status Code | 200 |
| eventType | “Done from client registration rule form” |
| outcome | “status ok” |
| client_id | Client ID specified in the request |
| message | “access token and refresh token revoked” |
Example
{"HTTP Status Code":"200","appName":"PegaDevelopment","client_id":"32538105954914023226","eventCategory":"OAuth 2.0","eventType":"Done from client registration rule form","id":"05d57aa5-30be-484a-a341-195ed419e07a","ipAddress":"10.233.67.0","message":"access token and refresh token revoked","nodeID":"pega-web-68484dd67f-fdwxd","operatorID":"solomSDE","outcome":"status ok","requestorIdentity":"20170317T160417","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 22:24:08:122"}
Delete client instance from rule form
Advice
Monitor daily. In production, the deletion of a client from the rule form should be extremely rare to non-existent. If the deletion is not expected, block access to the operator/IP address from which the request originated and restore the deleted client record.
Fields
| Field Name | Value/Description |
| eventType | “Client deletion” |
| message | “Client registration is deleted from rule form” |
| outcome | “Client deleted” |
Example
{"Http Status Code":"204","appName":"Company","client_id":"10721402601335077786","eventCategory":"OAuth 2.0","eventType":"Client deletion","id":"1e712ffa-09ad-4294-8703-17058cb3f3fe","ipAddress":"10.2.207.35","message":"Client registration is deleted from rule form","nodeID":"8b1bb39d3e5c4776c7b62c232ffa4133","operatorID":"Companyauthor","outcome":"Client deleted","requestorIdentity":"20211103T153639","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 15:56:37:523"}
Dynamic client registration
Advice
The system logs this event whenever a new client is created via the Pega API. Monitor daily. Any unexpected client registrations should be addressed immediately. Block the source of the requests and immediately delete the client record (at a minimum revoke access tokens via the rule form button).
Fields
| Field Name | Value/Description |
| HTTP Status | “201”, “400” |
| client_id | Registered client’s client ID value |
| eventType | “Done from client registration rule form”* |
| message | “client details saved successfully to the database”
“request parsing failed” |
| outcome | “invalid_request_data” |
*This message is misleading as only the Pega API endpoint generates this event. Creating a new client registration from the rule form does not generate this event.
Example 1 (successful registration)
{"HTTP Status Code":"201","appName":"PegaRULES","client_id":"91190346154444541571","eventCategory":"OAuth 2.0","eventType":"Done from client registration rule form","id":"fcaccfbf-1fa8-4c87-bd68-671a1ad38714","ipAddress":"10.233.67.0","message":"client details saved successfully to the database","nodeID":"pega-web-849fc7f948-k7zmx","operatorID":"abcdef","outcome":"client created","requestorIdentity":"20211115T114220","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 11:47:29:395"}
Example 2 (unsuccessful registration)
{"HTTP Status Code":"400","appName":"Company","eventCategory":"OAuth 2.0","eventType":"Done from client registration rule form","id":"e8440d38-f518-4b30-a69c-6316d5ebf861","ipAddress":"10.2.207.35","message":"Request parsing failed","nodeID":"8b1bb39d3e5c4776c7b62c232ffa4133","operatorID":"Companyauthor","outcome":"invalid_request_data","requestorIdentity":"20211103T153639","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 18:20:11:857"}
Resource API invocation using invalid access token
Advice
Monitor daily. Repeated events of access requests with an invalid token from a given user/IP address might indicate malicious activity. Examine the source of the requests and block if necessary.
Fields
| Field Name | Value/Description |
| Description | “Access token validation failed” |
| HTTP Status Code | “401” |
| eventType | “Access token validation while accessing resources” |
| Message | “Invalid token or expired” |
| outcome | “invalid_token” |
Example
{"Description":"Access token validation failed","HTTP Status Code":"401","appName":"PegaRULES","eventCategory":"OAuth 2.0","eventType":"Access token validation while accessing resources","id":"c69e56d4-3701-4d74-ad57-4aaf007f9c6f","ipAddress":"10.233.68.1","message":"Invalid token or expired.","nodeID":"pega-web-849fc7f948-k7zmx","outcome":"invalid_token","tenantID":"shared","timeStamp":"Mon 2021 Nov 15, 09:50:21:238"}