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 (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 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.
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.
- The overview details of the transaction. For a list of specific metadata elements, see Traffic logging reference.
- 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
X-Forwarded-Forheaders are common inclusions.
- 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.Note:
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.
- The component that generated the response. Valid values are
Third Party Service,
OpenID Provider, and
PingOneresponder type refers only to the PingOne Protect integration. When you're using PingOne as a token provider, PingAccess labels backchannel communications as either
Authorization Serverdepending on the context of the transaction.
- The time that it took to process specific components of the transaction.
These components include
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.
If you require specific HTML from a request or response, enable the
TRACE log level and check the PingAccess server log to find this
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.
- 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.
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:
- Enabling API audit traffic logging
- Enabling engine traffic logging
- Enabling agent traffic logging
- Enabling sideband traffic logging
- Enabling sideband client traffic logging
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.