OAuth 2.0 Security Event Monitoring

From PegaWiki
Revision as of 20:26, 24 January 2022 by Browl2 (talk | contribs) (Edited for consistency, grammar, and punctuation.)

Jump to navigation Jump to search


Curator Assigned Leon Brown
Request to Publish Yes
Description OAuth 2.0 security event monitoring advice
Version as of 8.6
Application Pega Platform
Capability/Industry Area Security


↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ Please Read Below ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓

Below are steps and guidance to get you started writing a design pattern.

  1. Click on the “info box” in the upper left hand corner of this draft and click the “Edit” button that appears.
  2. Complete the following fields in the “info box”, "Pega Infinity version", "Design pattern description", "Pega Platform or Application" and "Capability or Industry Area" then click “Apply changes” to save your updates.
  3. Begin writing your design pattern by clicking anywhere on the draft. To assist in the writing, a basic design pattern template has been provided as a guide. Feel free to use the template as needed or change it up to meet the needs of your content.
  4. Click the “Save page” button in the upper right hand side to save your work. If you leave the page and need to come back and continue working on it, click the "Watchlist" link located at the upper right hand side of any page and then click on the page you are looking for.
  5. When you are ready to publish, click on the “info box” in the upper left hand corner then click the “Edit” button. Update the “Request to Publish” field to “Yes”, click “Apply changes button” then click "Save page". Once saved, your content will be placed in the Curation/Editing queue for review and publication.

If you have any questions or need any assistance please reference the PegaWiki help located on the left hand navigation panel or contact us

↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ The above text will be removed prior to being published ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓


OAuth 2.0 Security Event Monitoring

Introduction[edit]

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, token revocation, and so on. This document also provides guidance for how to interpret the log's contents. For more information about the security events log, see https://community.pega.com/knowledgebase/articles/security/86/security-events-log.


All events are always enabled.

OAuth 2.0 Events.png

OAuth 2.0 Events[edit]

Fields common to all events[edit]

The following table lists the fields and their values that are the same for all data access 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[edit]

Advice[edit]

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[edit]

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[edit]

{"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[edit]

{"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[edit]

Advice[edit]

Monitor periodically.

Event message fields[edit]

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[edit]

{"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[edit]

Advice[edit]

Monitor regularly to identify unexpected token revocation requests. Block requests from IP addresses if requests are unexpected.

Fields[edit]

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 1 (failed token revocation request)[edit]

"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[edit]

This event is logged whenever the ‘Regenerate client secret’ button on the OAuth 2.0 Client Registration rule form is enabled.

Advice[edit]

Monitor periodically.


If this event is observed but not expected, block access to the operator/IP address from which the request occurred.

Fields[edit]

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[edit]

{"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[edit]

Advice[edit]

Monitor daily. Ensure all entries are legitimate requests for token revocation. Block requests from IP addresses for unexpected revocation requests.

Fields[edit]

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[edit]

{"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[edit]

Advice[edit]

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[edit]

Field Name Value/Description
eventType “Client deletion”
message “Client registration is deleted from rule form
outcome “Client deleted”

Example[edit]

{"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[edit]

Advice[edit]

This event is logged 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[edit]

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)[edit]

{"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)[edit]

{"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[edit]

Advice[edit]

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[edit]

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 1[edit]

{"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"}