Audit
2.0
1.0

The Audit feature is used to report and track auditable events to ensure the integrity of your system.

The Audit feature introduces an infrastructure that serves two purposes:

  • Confirming the effectiveness and integrity of the existing configuration

  • Identifying areas where improvement to the configuration might be needed

The Audit feature can capture a range of auditable events that include events related to authentication, authorization, and logout. The feature provides a default audit file handler implementation that emits human-readable audit records to a file-based log. Each audit record is emitted in JSON format.

The Audit 2.0 feature (audit-2.0) provides the same audit records as the Audit 1.0 feature (audit-1.0) except it does not generate records for REST Handler applications. If you need to keep audit records for REST Handler applications, use audit-1.0.

Enabling this feature

To enable the Audit 2.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>audit-2.0</feature>

Examples

Manage audit log files

The following example shows how to set the maximum file size to 100 MB and set the maximum number of archived audit log files to 50. You can also set the compact attribute to true to print the entire audit record on one line within the audit log:

<auditFileHandler maxFiles="50" maxFileSize="100" compact=”true”>
</auditFileHandler>

Configure the audit events to log

To specify only the audit events and outcomes that might be relevant in an environment, the events element can be defined with the audit event name and outcome. The following example specifies audit events and outcomes in the auditFileHandler element:

<auditFileHandler maxFiles="5" maxFileSize="20" compact="true">
    <events name="AuditEvent_1" eventName="SECURITY_AUTHN" outcome="SUCCESS"/>
    <events name="AuditEvent_2" eventName="SECURITY_AUTHN" outcome="REDIRECT"/>
    <events name="AuditEvent_3" eventName="SECURITY_AUTHN" outcome="FAILURE"/>
    <events name="AuditEvent_4" eventName="SECURITY_AUTHZ"/>
</auditFileHandler>

Encrypt and sign audit data

The following example shows the audit file handler with encryption and signing enabled. The encrypt and sign attributes must be specified in the auditFileHandler element along with the alias names of the certificates and the keystores that contain the certificates. The keystore element contains the private or public key that is used to encrypt and sign the data:

<keyStore id="auditEncKeyStore” password="Liberty" location="server1/resources/security/AuditEncryptionKeyStore.jks" type="JKS" />

<keyStore id="auditSignKeyStore" password="{aes}EzY9Oi0rJg==" location="server1/resources/security/AuditSigningKeyStore2.jks" type="JKS" />

<auditFileHandler encrypt="true" encryptAlias="#auditencryption#" encryptKeyStoreRef="auditEncKeyStore" sign="true" signingAlias="auditsigning2" signingKeyStoreRef="auditSignKeyStore"
</auditFileHandler>

Set the audit log format

The JSON logging format makes it easier to manage log data by providing more structure to generated data. The following example shows how to configure the Audit feature to generate audit logs in the JSON logging format:

<logging messageFormat="json" messageSource="audit,message"/>

Features that this feature enables

Supported Java versions

  • JavaSE-1.8

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

  • JavaSE-22.0

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

com.ibm.websphere.appserver.audit-2.0; type="osgi.subsystem.feature"