Writing audit logs for Splunk

Ping Identity provides a custom Splunk app for PingAccess to process audit logs generated by a PingAccess deployment.

Before you begin

Go to the Splunk website and download Splunk.
Install Splunk.

About this task

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 that you can generate reports, graphs, and other data visualization from.

The PingAccess app for Splunk is available separately. It requires enterprise-licensed (or trial) installation of the Splunk software and the Splunk Universal Forwarder, which collects data from the PingAccess Splunk audit logs. The application includes additional documentation on installation and available features.

The PingAccess app for Splunk 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 logs. To write these specially formatted logs to the PingAccess log directory, perform the following steps.

The PingAccess app for Splunk was designed to use the default Splunk log pattern configuration. If you have changed the output format of the Splunk rolling files, those changes could impact the functionality of the PingAccess app for Splunk.

Steps

Set up your Splunk server.
1. Enable a receiver to listen for data from the servers hosting PingAccess.
  
  For more information, see the Splunk documentation.
2. Install the PingAccess app for Splunk.
  
  To download the free application from Splunkbase.splunk.com, search for PingAccess.
  
  For installation instructions, see the Splunk Add-on documentation.

Configure PingAccess to output the following available Splunk audit logs:

pingaccess_engine_audit_splunk.log
pingaccess_api_audit_splunk.log
pingaccess_agent_audit_splunk.log

These logs output to <PA_HOME>/log/ by default.

Edit the <PA_HOME>/conf/log4j2.xml file.

In the Audit Log Configuration section, edit the apiaudit, engineaudit, and agentaudit logger configurations to uncomment the Splunk AppenderRef.

Example:

<!-- ======================= -->
<!-- Audit log configuration -->
<!-- ======================= -->
<Logger name="apiaudit" level="INFO" additivity="false">
    <AppenderRef ref="APIAuditLog-File"/>
    <!--<AppenderRef ref="ApiAuditLog-Database-Failover"/>-->
    <!--<AppenderRef ref="ApiAuditLog-SQLServer-Database-Failover"/>-->
    <!--<AppenderRef ref="ApiAuditLog-PostgreSQL"/>-->
     <AppenderRef ref="ApiAudit2Splunk"/>
    <!--<AppenderRef ref="ApiAuditLog-HarFile"/>-->
</Logger>
<Logger name="engineaudit" level="INFO" additivity="false">
    <AppenderRef ref="EngineAuditLog-File"/>
    <!--<AppenderRef ref="EngineAuditLog-Database-Failover"/>-->
    <!--<AppenderRef ref="EngineAuditLog-SQLServer-Database-Failover"/>-->
    <!--<AppenderRef ref="EngineAuditLog-PostgreSQL"/>-->
     <AppenderRef ref="EngineAudit2Splunk"/>
    <!--<AppenderRef ref="EngineAuditLog-HarFile"/>-->
</Logger>
<Logger name="agentaudit" level="INFO" additivity="false">
    <AppenderRef ref="AgentAuditLog-File"/>
    <!--<AppenderRef ref="AgentAuditLog-Database-Failover"/>-->
    <!--<AppenderRef ref="AgentAuditLog-SQLServer-Database-Failover"/>-->
    <!--<AppenderRef ref="AgentAuditLog-PostgreSQL"/>-->
     <AppenderRef ref="AgentAudit2Splunk"/>
    <!--<AppenderRef ref="AgentAuditLog-HarFile"/>-->
</Logger>
<Logger name="sidebandclientaudit" level="INFO" additivity="false">
    <AppenderRef ref="SidebandClientAuditLog-File"/>
    <!--<AppenderRef ref="SidebandClientAuditLog-Database-Failover"/>-->
    <!--<AppenderRef ref="SidebandClientAuditLog-SQLServer-Database-Failover"/>-->
    <!--<AppenderRef ref="SidebandClientAuditLog-PostgreSQL"/>-->
     <AppenderRef ref="SidebandClientAudit2Splunk"/>
    <!--<AppenderRef ref="SidebandClientAuditLog-HarFile"/>-->
</Logger>
<Logger name="sidebandaudit" level="INFO" additivity="false">
    <AppenderRef ref="SidebandAuditLog-File"/>
    <!--<AppenderRef ref="SidebandAuditLog-Database-Failover"/>-->
    <!--<AppenderRef ref="SidebandAuditLog-SQLServer-Database-Failover"/>-->
    <!--<AppenderRef ref="SidebandAuditLog-PostgreSQL"/>-->
     <AppenderRef ref="SidebandAudit2Splunk"/>
    <!--<AppenderRef ref="SidebandAuditLog-HarFile"/>-->
</Logger>

Uncomment the RollingFile appender references for the ApiAudit2Splunk, EngineAudit2Splunk, and AgentAudit2Splunk RollingFile elements.

Example:

This is the default configuration for the ApiAudit2Splunk file:

<!--
<RollingFile name="ApiAudit2Splunk"
             fileName="${sys:pa.home}/log/pingaccess_api_audit_splunk.log"
             filePattern="${sys:pa.home}/log/pingaccess_api_audit_splunk.%d{yyyy-MM-dd}.log"
             ignoreExceptions="false">
    <PatternLayout>
        <pattern>%d{ISO8601} exchangeId="%X{exchangeId}" trackingId="%X{AUDIT.trackingId}" subject="%X{AUDIT.subject}" authMech="%X{AUDIT.authMech}" client="%X{AUDIT.client}" method="%X{AUDIT.method}" requestUri="%X{AUDIT.requestUri}" responseCode="%X{AUDIT.responseCode}" responder="%X{AUDIT.responder}" engineHostname="%X{AUDIT.host}" %n</pattern>
    </PatternLayout>
    <Policies>
        <TimeBasedTriggeringPolicy />
    </Policies>
</RollingFile>
 -->

This is the updated configuration for the ApiAudit2Splunk file, with the RollingFile uncommented and no other changes:

<RollingFile name="ApiAudit2Splunk"
             fileName="${sys:pa.home}/log/pingaccess_api_audit_splunk.log"
             filePattern="${sys:pa.home}/log/pingaccess_api_audit_splunk.%d{yyyy-MM-dd}.log"
             ignoreExceptions="false">
    <PatternLayout>
        <pattern>%d{ISO8601} exchangeId="%X{exchangeId}" trackingId="%X{AUDIT.trackingId}" subject="%X{AUDIT.subject}" authMech="%X{AUDIT.authMech}" client="%X{AUDIT.client}" method="%X{AUDIT.method}" requestUri="%X{AUDIT.requestUri}" responseCode="%X{AUDIT.responseCode}" responder="%X{AUDIT.responder}" engineHostname="%X{AUDIT.host}" %n</pattern>
    </PatternLayout>
    <Policies>
        <TimeBasedTriggeringPolicy />
    </Policies>
</RollingFile>

Set up the Splunk Universal Forwarder.
1. Download the Splunk Universal Forwarder from Splunk and install it on the PingAccess server.
2. Configure the Splunk Universal Forwarder to monitor the three Splunk log files (pingaccess_engine_audit_splunk.log, pingaccess_api_audit_splunk.log, and pingaccess_agent_audit_splunk.log) and forward the data to the receiver you configured.

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