PingFederate Server

Writing logs to databases

Database logging replaces file logging. For each qualified database server, PingFederate provides scripts to create database tables for the audit log, the provisioner audit log, the provisioner log, and the server log.

About this task

You can find these scripts in the <pf_install>/pingfederate/server/default/conf/log4j/sql-scripts directory.

include:::partial$pf_rc_notes.adoc[tags=pf_ph_testedJdbcDriver]To obtain the database driver .jar file, contact your database vendor. Install the database driver file to the <pf_install>/pingfederate/server/default/lib directory, and then restart the server.

Failover file logging is provided in the event that database logging fails for any reasons. By default, PingFederate retries database logging every minute. Messages written to log files during failover periods are not copied over to the database server.

You enable database logging for the audit log, the provisioner audit log, the provisioner log, and the server log in the log4j2.xml file.

Steps

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

  2. After the Preserve messages in a local file section, for each log that you want to enable database logging, uncomment the preset Java Database Connectivity (JDBC) appender configuration based on the choice of your database server.

    Audit log

    • Oracle MySQL - SecurityAuditToMySQLDB

    • Oracle Database - SecurityAuditToOracleDB

    • PostgreSQL - SecurityAuditToPostgreSQLDB

    • Microsoft SQL Server - SecurityAuditToSQLServerDB

    Provisioner audit log

    • Oracle MySQL - OutboundProvisionerEventToMySQLDB

    • Oracle Database - OutboundProvisionerEventToOracleDB

    • PostgreSQL - OutboundProvisionerEventToPostgreSQLDB

    • Microsoft SQL Server - OutboundProvisionerEventToSQLServerDB

    Provisioner log

    • Oracle MySQL - ProvisionerLogToMySQLDB

    • Oracle Database - ProvisionerLogToOracleDB

    • PostgreSQL - ProvisionerLogToPostgreSQLDB

    • Microsoft SQL Server - ProvisionerLogToSQLServerDB

    Server log

    • Oracle MySQL - ServerLogToMySQLDB

    • Oracle Database - ServerLogToOracleDB

    • PostgreSQL - ServerLogToPostgreSQLDB

    • Microsoft SQL Server - ServerLogToSQLServerDB

      Each JDBC appender is followed by two related appenders, PingFailover and RollingFile. Together, they create a running *-failover.log file in the log directory in the event that database logging fails for any reason. Both appenders must also be enabled (uncommented).

      For more information about each appender, review inline comments and notes in the log4j2.xml file.

  3. Replace placeholder parameter values in log4j2.db.properties in the same conf directory for the applicable Java Database Connectivity (JDBC) servers.

    The parameter values provide access to the database. Test and validate access prior to production deployment. Like log4j2.xml, log4j2.db.properties is also individually managed per PingFederate server. This flexibility allows multiple PingFederate nodes in a clustered environment to write messages to different destinations, as needed.

    You can obfuscate the password used to access the database by running the obfuscate utility, located in the <pf_install>/pingfederate/bin directory: obfuscate.bat for Windows or obfuscate.sh for Linux. Use the actual password as an argument and copy the entire result into the value for the password parameter in log4j2.db.properties.

  4. Uncomment the appender reference, <AppenderRef/>, in the associated logger elements, as described inline in the log4j2.xml file.

    Audit log

    Uncomment the corresponding PingFailover appender references from the following Logger elements located under the Loggers section:

    • Browser 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 log

    Uncomment the corresponding PingFailover appender reference from the ProvisionerAuditLogger Logger element located under the Set up the Outbound provisioner audit logger section.

    Provisioner log

    Uncomment the corresponding PingFailover appender reference from the com.pingidentity.provisioner AsyncLogger element located under the Loggers section.

    Server log

    Uncomment the corresponding PingFailover appender reference from the root element located under the Set up the Root Logger section, near the end of the file.

    As indicated in the IMPORTANT comments for the loggers, you must also remove some of the existing appender references.

  5. Optional: For the audit log and the provisioner audit log, you can configure elements for database logging in the ConversionPattern appender parameter, as needed.