PingFederate Server

Security audit logging

PingFederate records a subset of transaction log information with additional details at runtime, intended to facilitate security auditing and regulatory compliance.

The system records activities from single sign-on (SSO), single logout (SLO), OAuth, WS-Trust STS, and System for Cross-domain Identity Management (SCIM) inbound provisioning transactions in the security audit log, the audit.log file, located in the <pf_install>/pingfederate/log directory. You can output security audit log information to different formats, including databases, CEF, and Splunk.

Outbound provisioning transactions are not included in the security audit log. Instead, they are recorded in the outbound provisioning audit log, the provisioner-audit.log file, located in the <pf_install>/pingfederate/log directory.

The following tables describe the default and available fields. PingFederate separates each field by a vertical pipe (|). As needed, fields are configurable by editing the <pf_install>/pingfederate/server/default/conf/log4j2.xml file.

Default fields, in the order that PingFederate records them in the security audit log
Field Description

%d

The transaction time.

trackingid

The tracking ID values uniquely identify user sessions, useful for correlating log messages in the audit and server logs.

event

The type of transaction. For example, SSO, OAuth, AUTHN_ATTEMPT, AUTHN_REQUEST, AUTHN_SESSION_CREATED, AUTHN_SESSION_USED, AUTHN_SESSION_DELETED, and SRI_REVOKED.

AUTHN_ATTEMPT and AUTHN_REQUEST indicate an authentication attempt against an identity provider (IdP) adapter instance and an authentication request sent to another IdP partner, through an IdP connection, respectively.

AUTHN_SESSION_CREATED and AUTHN_SESSION_USED indicate the creation and employing of a PingFederate session, respectively.

AUTHN_SESSION_DELETED indicates that a PingFederate session has been removed as a result of a front-channel browser-based logout request via the SAML 2.0 or WS-Federation protocol.

SRI_REVOKED indicates that a PingFederate session has been added to the session revocation list.

USER_KEY_AND_SRI_ASSOCIATED indicates a unique user key is associated with a PingFederate session.

subject

The subject of the transaction or authentication attempt.

ip

The incoming IP address.

app

The target service provider (SP) application, the email verification endpoint, or the profile management page, when applicable and available.

connectionid

The partner identifier associated with the transaction. The OAuth client ID value for OAuth transactions. The ID of the authentication policy contract referenced by the local identity profile that has been invoked for the purpose of accessing the email verification endpoint or the profile management page.

protocol

The associated identity protocol; for example, SAML20 or OAuth20.

host

The host name or IP address of the PingFederate server.

role

The role PingFederate played for the transaction.

status

The status of the transactions.

adapterid

The ID of an adapter instance.

Consider adding the authenticationsourceid and targetsessionid fields to record additional information about the request.

description

The description of an authentication failure, when such information is available from the authentication source, or an authorization failure from an erroneous OAuth authorization request.

responsetime

The time elapsed in milliseconds from when the system receives a final request for a transaction, to when the system writes the audit message. This value serves as an approximation of total transaction processing time and can be useful for monitoring trends.
Other available fields, in alphabetical order
Field Description

accessgrantguid

The GUID of the OAuth access grant, for OAuth transactions.

assertionid

The unique ID for the SAML assertion.

attrackingid

The tracking ID for OAuth access token. You can use this ID to analyze the flow of OAuth access tokens in the audit log and between PingFederate and PingAccess.

attributes

The user attributes received (for an SP log), sent (for an IdP log), or provided by the user through the self-service registration or profile management page.

authenticationsourceid

An array of one or more IdP adapters, one or more IdP connections, and identity profile, if any, invoked in an authentication or logout flow. For example, [adapter.HTMLFormSimplePCV, idpConnection.IdP, localIdentity.A8me9rySDn1aIM48]

authnsessionexpiry

The expiry of an authentication session that has just been created or used.

connectionname

The partner name associated with the transaction. The OAuth client name for OAuth transactions. The name of the authentication policy contract referenced by the local identity profile that has been invoked for the purpose of accessing the email verification endpoint or the profile management page.

granttype

The OAuth grant type.

header\{anHttpRequestHeader}

The HTTP request header value identified by the header name. The header name is case-insensitive. For example, header{user-agent} and header{User-Agent} are equivalent.

To record multiple headers, repeat the header field, as illustrated in the following sample pattern.

<pattern>...| %header\{accept-language}| %header\{dnt}  %n</pattern>

Given this partial sample, PingFederate includes both the accept-language and dnt HTTP request header values when recording entries in the audit log.

To record values from all HTTP request headers, look for the org.sourceid.servlet.filter.HttpRequestHeaderFilter Logger in the log4j2.xml file.

This capability is turned off by default and is likely suitable only for testing and troubleshooting purposes.

httprequestid

The ID of the HTTP request. This can be used for correlation across external systems (like PingDirectory) and for debugging purposes in the server log. This field is optional.

initiator

The federation role that initiated the SSO or SLO: SP or IDP.

Applicable only to SAML 2.0 transactions.

inmessagetype

The incoming message type.

Possible values are Request or Response.

inresponseto

The value of the InResponseTo attribute of an SSO or SLO response.

inxmlmsg

The incoming message. For example, a SAML AuthnRequest or the information pertaining to an OAuth request.

localuserid

The local ID used for the transaction, when account linking is enabled at the SP.

outurl

The URL where the protocol response was sent. For security reason, parameters and fragments are excluded.

outxmlmsg

The outgoing message. For example, a SAML Response or the information pertaining to a response for an OAuth request.

parameter\{anHttpRequestParameter}

The value of the HTTP request parameter identified by the parameter name. The parameter name is case-sensitive.

To record multiple parameters, repeat the parameter field, as illustrated in the following sample pattern.

<pattern>...| %parameter\{foo1}| %parameter\{Foo3}  %n</pattern>

Given this partial sample, PingFederate includes both the foo1 and Foo3 HTTP request parameter values when recording entries in the audit log.

To record values from all HTTP request parameter, look for the org.sourceid.servlet.filter.HttpRequestParameterFilter Logger in the log4j2.xml file.

This capability is turned off by default and is likely suitable only for testing and troubleshooting purposes.

pfversion

The PingFederate version.

requestid

The ID of a SAML request.

requeststarttime

The start time of the request in milliseconds since midnight, January 1, 1970 UTC.

responseid

The ID of a SAML response.

sessiongroupid

The internal ID for a group of persistent authentication sessions associated with a single browser instance through the PF.PERSISTENT cookie. It is only set if the request has triggered a session lookup.

sri

The session reference identifier (SRI) for the user, which can be passed to the session revocation API to revoke the user’s sessions. It is only set if the request has triggered a session lookup.

stspluginid

The ID for the token processor or token generator instance.

Applicable only to WS-Trust STS transactions.

targetsessionid

An array of one or more SP adapters or SP connections invoked in an authentication or logout flow.

trackedparameter\{anHttpRequestParameter}

The value of the tracked HTTP request parameter identified by the parameter name. The parameter name is case-sensitive.

The PingFederate policy engine is capable of tracking HTTP request parameters that it receives from the initial request and making them available to authentication sources, selector instances, and contract mappings throughout the policy. As needed, parameters can be configured as such on the Tracked HTTP Parameterswindow. For more information about tracked parameters, see Policies.

To record multiple parameters, repeat the trackedparameter field, as illustrated in the following sample pattern.

<pattern>...| %trackedparameter\{foo2}| %trackedparameter\{Foo4}  %n</pattern>

Given this partial sample, PingFederate includes both the foo2 and Foo4 HTTP request parameter values when recording entries in the audit log.

If the parameter, as indicated by <anHttpRequestParameter>, has not been configured as a parameter to be tracked by the policy engine, PingFederate does not record the parameter value in the audit log.

uniqueuserkey

The unique user key tied to the user’s authentication sessions. It is only set if the user authenticated using an IdP adapter that has configured a unique user key attribute.

validatorid

The ID of the Password Credential Validator (PCV) instance, for the successful attempts.

virtualserverid

The virtual server ID of a request, if applicable.