Log traffic for troubleshooting

Enable HTTP Archive (HAR) file audit logging to troubleshoot specific issues or gather more detailed information on the requests and responses sent to and from applications.

When you enable HAR file audit logging for a specific logging category, such as engine audit logging, PingAccess generates a HAR-formatted audit log file for that log category. For example, the HAR-formatted file for the engine audit logging category is the engine audit log HAR file or <PA_HOME>/log/pingaccess_engine_audit_har.log.

The HAR-formatted audit logs contain detailed records of specific transactions and sub-transactions between PingAccess and other systems, such as the configured OAuth authorization server (OAuth AS) or a system acting on behalf of the end user.

Audit log records are called transactions. One audit log record equals one transaction. A transaction captures an end-user transaction or an event originating from PingAccess. Sub-transactions are the request-response pairs sent through the HTTP or HTTPS connections.

You can use regex filters to include or exclude certain results from the logs.

HAR format within PingAccess is not exactly equivalent to a browser’s HAR format. A standard HAR file is a complete JavaScript Object Notation (JSON) object, whereas the PingAccess HAR-formatted audit log file is a JSON sequence of HAR objects. Each log entry is a complete HAR file, and entries are continually added to the audit log as new information comes in.

Standard HAR tooling doesn’t understand what to do with a JSON sequence, so you must reformat a HAR-formatted audit log before you can view it or parse it with a HAR reader. For more information on how to convert a snapshot instance of the HAR-formatted audit log file into a complete JSON object for parsing, see Parsing HAR-formatted audit log files.

Structure of a HAR file log entry

Each HAR file entry within the HAR-formatted audit log file contains an array of audited PingAccess transactions, and each transaction contains one or more request-response pairs. Transactions can provide insight into PingAccess’s internal processing.

If an incoming request to PingAccess requires it to make an outgoing request to a site application before it can provide a response, or if you’re using an API gateway integration with PingAccess, then a transaction can contain up to two sub-transactions (request-response pairs):

The first sub-transaction is the original request from the client or API gateway and the response from PingAccess, which it might have modified from the original backend response.
The second sub-transaction is the request data sent from PingAccess, which PingAccess might have modified from the original request, to the backend site or API gateway and the original response from the site or API gateway.

For most other transactions, such as those seen in agent auditing or requests made from PingAccess to other external systems, there is usually only one sub-transaction.

PingAccess records entries as request-response pairs in the audit log file, so sub-transactions aren’t ordered sequentially. For example:

Sequentially, a user’s inbound request prompts PingAccess to make an outbound request. The response to PingAccess’s outbound request then determines PingAccess’s final response to the user.

PingAccess’s response to the user derives from the response to its own request, but the audit log records PingAccess’s response before the response it receives. This is because the user’s request and PingAccess’s response to the user pair together as a sub-transaction. Likewise, PingAccess’s request pairs with the response it receives.

You can use sub-transactions to:

Check PingAccess’s connections to PingFederate.
Follow OAuth and OpenID Connect (OIDC) flows to identify where issues might lie.
Investigate PingAccess policy issues.
Review the HTTP headers that PingAccess receives to investigate virtual host parsing and base configuration mapping.
Review the HTTP headers that PingAccess sends.

Components of a sub-transaction

Metadata

The overview details of the transaction. For a list of specific metadata elements, see Traffic logging reference.

URL

The URL of the transaction. Path varies based on whether the transaction is an input to or output from PingAccess.

HTTP Method

The HTTP method used in the transaction.

HTTP Headers

The HTTP headers included in the transaction. For input to PingAccess, the Host and X-Forwarded-For headers are common inclusions.

Cookies

The cookies included in the transaction. These can be cookies from PingAccess and PingFederate. If the cookies aren’t encrypted, you can view their contents.

The PingAccess cookie contains all of the request’s identity mappings and the access token from PingFederate, if PingFederate is the AS. This is all of the information that PingAccess requires to make authorization and mapping decisions.

Responder

The component that generated the response. Valid values are PingAccess, PingOne, Site, Third Party Service, OpenID Provider, and Authorization Server.

The PingOne responder type refers only to the PingOne Protect integration. When you’re using PingOne as a token provider, PingAccess labels backchannel communications as either OpenID Provider or Authorization Server depending on the context of the transaction.

Timings

The time that it took to process specific components of the transaction. These components include %d, AUDIT.reqReceivedMillisec, AUDIT.reqSentMillisec, AUDIT.respReceivedMillisec, AUDIT.respSentMillisec, AUDIT.roundTripMS, and AUDIT.proxyRoundTripMS. For more information on these components, see Security audit logging.

Failed Policy Components

The rule or rule set name, type, and class of the policy component that failed in the transaction. Failed policy components are only available in the engine log.

PingAccess HAR file responses can contain binary and text from CSS, fonts, JavaScript, and the HTML from PingAccess errors. HAR file responses don’t contain HTML responses from the back-end systems, but do indicate the length of the message’s HTML body.

If you require specific HTML from a request or response, enable the TRACE log level and check the PingAccess server log to find this information.

Alternately, you can enable verbose logging for the HTTP Client and HTTP Application log categories in the PingAccess administrative console. For more information, see Log settings.

Which log categories support HAR file audit logging?

API audit log: Requests made to the PingAccess APIs.
Engine audit log: Requests made to or by the PingAccess engine.
Agent audit log: Requests made to or by a PingAccess agent.
Sideband audit log: Requests made to the sideband client.
Sideband client audit log: Requests made to or by the sideband client integration.

For more information on these categories, see Security audit logging.

How do I enable HAR file audit logging?

When you enable HAR file audit logging for a log category, you can filter the types of entries to include in the log and specify what information you want to log. For more information, see the following topics:

HAR-formatted audit log files are significantly larger than other log files and can include credentials. You should either carefully configure regex filters to exclude credential information or enable these logs only for troubleshooting purposes. Delete the files when they are no longer necessary.