PingFederate Server

Writing audit logs for Splunk

Ping Identity provides a custom Splunk App for PingFederate to process audit logs generated by a PingFederate deployment. Splunk is an enterprise software that allows for monitoring, reporting, and analysis of consolidated log files.

Before you begin

  • Download and install Splunk

About this task

Splunk captures and indexes real-time data into a single searchable repository where reports, graphs, and other data visualization can be generated.

The PingFederate Splunk App provides rich system monitoring and reporting, including:

  • Current transaction and system reports

  • Service reports, such as a daily usage report, and identity provider (IdP) and service provider (SP) reports per connection

  • Trend reports, such as weekly and monthly usage reports, and trend analysis

Splunk uses a specially formatted version of the audit log splunk-audit.log, which you can write to the PingFederate log directory when you complete the setup steps.

The Splunk App for PingFederate is available separately. It requires enterprise-licensed, or trial installation of the Splunk software and the Splunk Universal Forwarder, which is needed to collect data from the PingFederate audit log for Splunk. The application includes additional documentation on installation and available features. To download the free application, go to splunkbase.splunk.com and search for PingFederate.

Steps

  1. Set up your Splunk server.

    1. Enable a receiver to listen for data from the PingFedrate server.

      For more information, see the Splunk documentation.

    2. Install Splunk App for PingFederate.

  2. Configure PingFederate to write audit log messages to the <pf_install>/pingfederate/log/splunk-audit.log file.

    1. Edit <pf_install>/pingfederate/server/default/conf/log4j2.xml.

    2. Locate the following Logger elements located under the Loggers section:

      • Browser single sign-on (SSO) SP and adapter-to-adapter - org.sourceid.websso.profiles.sp.SpAuditLogger

      • Browser SSO IdP and adapter-to-adapter - org.sourceid.websso.profiles.idp.IdpAuditLogger

      • OAuth authorization server - org.sourceid.websso.profiles.idp.AsAuditLogger

      • Dynamic Client Registration - org.sourceid.websso.profiles.idp.ClientRegistrationAuditLogger

      • WS-Trust STS, IdP, and SP - org.sourceid.wstrust.log.STSAuditLogger

      • Provisioner Audit Logger - ProvisionerAuditLogger

    3. Uncomment the SecurityAudit2Splunk RollingFile appender reference, <appender-ref ref="SecurityAudit2Splunk"/>, from one or more of the Logger elements.

      Example:

      For example, the default logger for an IdP audit log reads as follows.

      <Logger name="org.sourceid.websso.profiles.idp.IdpAuditLogger"
        level="INFO" additivity="false" includeLocation="false">
    <appender-ref ref="SecurityAudit2File" />
    <!--
        <appender-ref ref="SecurityAuditToCEFSyslog-FAILOVER"/>
        <appender-ref ref="SecurityAuditToCEFFile"/>
        <appender-ref ref="SecurityAuditToMySQLDB-FAILOVER"/>
        <appender-ref ref="SecurityAuditToPostgreSQLDB-FAILOVER" />
        <appender-ref ref="SecurityAuditToSQLServerDB-FAILOVER"/>
        <appender-ref ref="SecurityAuditToOracleDB-FAILOVER"/>
        <appender-ref ref="SecurityAudit2Splunk"/>
    -->
</Logger>

      To log Browser SSO IdP audit log messages to splunk-audit.log, update the Logger element as follows.

      <Logger name="org.sourceid.websso.profiles.idp.IdpAuditLogger"
        level="INFO" additivity="false" includeLocation="false">
     <appender-ref ref="SecurityAudit2Splunk"/>
    <!--
        <appender-ref ref="SecurityAuditToCEFSyslog-FAILOVER"/>
        <appender-ref ref="SecurityAuditToCEFFile"/>
        <appender-ref ref="SecurityAuditToMySQLDB-FAILOVER"/>
        <appender-ref ref="SecurityAuditToPostgreSQLDB-FAILOVER" />
        <appender-ref ref="SecurityAuditToSQLServerDB-FAILOVER"/>
        <appender-ref ref="SecurityAuditToOracleDB-FAILOVER"/>
        <appender-ref ref="SecurityAudit2Splunk"/>
         <appender-ref ref="SecurityAudit2File" />
    -->
</Logger>

      For auditing of adapter-to-adapter events, you must enable both the IdP and SP loggers.

    4. Uncomment the following section:

      <RollingFile name="SecurityAudit2Splunk" fileName="${sys:pf.log.dir}/splunk-audit.log"
filePattern="${sys:pf.log.dir}/splunk-audit.%d

{yyyy-MM-dd}
.log"
ignoreExceptions="false">
<PatternLayout>
<pattern>%d trackingid="%X

{trackingid}
" event=%X

{event}
subject="%X

{subject}
" ip=%X

{ip}
app=%X

{app}
connectionid=%X

{connectionid}
protocol="%X

{protocol}
" pfhost=%X

{host}
role=%X

{role}
status=%X

{status}
adapterid=%X

{adapterid}
description="%X

{description}
" responsetime=%X

{responsetime}
inmessagetype="%X

{inmessagetype}
" %n</pattern>
</PatternLayout>
<Policies>
<TimeBasedTriggeringPolicy />
</Policies>
</RollingFile>

  3. Set up Splunk Universal Forwarder.

    1. Download the Splunk Universal Forwarder from Splunk and install it on the PingFederate server.

    2. Configure the Splunk Universal Forwarder to monitor the splunk-audit.log file and forward the data to the receiver configured in [pf_step_splunkEnableReceiver].

    For detailed installation and configuration instructions, see the Splunk Universal Forwarder documentation.