Splunk is enterprise software that allows for monitoring, reporting, and analyzing consolidated log files. Splunk captures and indexes real-time data into a single searchable repository from which 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 IdP and SP reports per connection
  • Trend reports such as weekly and monthly usage reports, and trend analysis

The application uses a specially formatted version of the audit log (splunk-audit.log), which is written to the PingFederate log directory when the setup steps described below are followed.

Note:

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. Download the free application from splunkbase.splunk.com. (Search for PingFederate.)

  1. Set up your Splunk server.
    1. If you have not done so, download and install Splunk.
    2. Enable a receiver to listen for data from the PingFedrate server.
      For more information, please refer to Splunk documentation (docs.splunk.com/Documentation/Forwarder/7.1.2/Forwarder/HowtoforwarddatatoSplunkEnterprise).
    3. 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. Look for the following Logger elements located under the Loggers section:
      • org.sourceid.websso.profiles.sp.SpAuditLogger (Browser SSO SP and adapter-to-adapter)
      • org.sourceid.websso.profiles.idp.IdpAuditLogger (Browser SSO IdP and adapter-to-adapter)
      • org.sourceid.websso.profiles.idp.AsAuditLogger (OAuth authorization server)
      • org.sourceid.websso.profiles.idp.ClientRegistrationAuditLogger (Dynamic Client Registration)
      • org.sourceid.wstrust.log.STSAuditLogger (WS-Trust STS, IdP and/or SP)
    3. Uncomment the SecurityAudit2Splunk RollingFile appender reference (<appender-ref ref="SecurityAudit2Splunk"/>) from the one or more of the Logger elements.

      For example, the default logger for an IdP audit log reads:

      
      <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>
      Note:

      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 (www.splunk.com/en_us/download/universal-forwarder.html) 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 step 1b.
    For detailed installation and configuration instructions, see Splunk documentation (docs.splunk.com/Documentation/Forwarder/7.1.2/Forwarder/HowtoforwarddatatoSplunkEnterprise).