Chapter 3. Configuring audit logging in Elytron You can use Elytron to complete security audits on triggering events. Security auditing refers to triggering events, such as writing to a log, in response to an authorization or authentication attempt. The type of security audit performed on events depends on your security realm configuration. 3.1. Elytron audit logging After you enable audit logging with the elytron subsystem, you can log Elytron authentication and authorization events within the application server. Elytron stores audit log entries in either JSON or SIMPLE formats. Use SIMPLE for human readable text format or JSON for storing individual events in JSON . Elytron audit logging differs from other types of audit logging, such as audit logging for the JBoss EAP management interfaces. Elytron disables audit logging by default, however, you can enable audit logging by configuring any of the following log handlers. You can also add the log handler to a security domain. File audit logging For more information, see Enabling file audit logging in Elytron . Periodic rotating file audit logging For more information, see Enabling periodic rotating file audit logging in Elytron . Size rotating file audit logging For more information, see Enabling size rotating file audit logging in Elytron . syslog audit logging For more information, see Enabling syslog audit logging in Elytron . Custom audit logging For more information, see Using custom security event listeners in Elytron . You can use the aggregate-security-event-listener resource to send security events to more destinations, such as loggers. The aggregate-security-event-listener resource delivers all events to all listeners specified in the aggregate listener definition. 3.2. Enabling file audit logging in Elytron File audit logging stores audit log messages in a single file within your file system. By default, Elytron specifies local-audit as the file audit logger. You must enable local-audit so that it can write Elytron audit logs to EAP_HOME/standalone/log/audit.log on a standalone server or EAP_HOME/domain/log/audit.log for a managed domain. Prerequisites You have secured an application. For more information, see Creating an aggregate-realm in Elytron . Procedure Create a file audit log. Syntax Example Add the file audit log to a security domain. Syntax Example Verification In a browser, log in to your secured application. For example, to log in to the application created in Using a security domain to authenticate and authorize application users , navigate to http://localhost:8080/simple-webapp-example/secured and log in. Navigate to the directory configured to store the audit log. If you use the example commands in the procedure, the directory is EAP_HOME /standalone/log. Note that a file called file-audit.log is created. It contains the logs of the events triggered by logging in to the application. Example file-audit.log file Additional resources file-audit-log attributes 3.3. Enabling periodic rotating file audit logging in Elytron You can use the elytron subsystem to enable periodic rotating file audit logging for your standalone server or a server running as a managed domain. Periodic rotating file audit logging automatically rotates audit log files based on your configured schedule. Periodic rotating file audit logging is similar to default file audit logging, but periodic rotating file audit logging contains an additional attribute: suffix . The value of the suffix attribute is a date specified using the java.time.format.DateTimeFormatter format, such as .yyyy-MM-dd . Elytron automatically calculates the period of the rotation from the value provided with the suffix. The elytron subsystem appends the suffix to the end of a log file name. Prerequisites You have secured an application. For more information, see Creating an aggregate-realm in Elytron . Procedure Create a periodic rotating file audit log. Syntax Example Add the periodic rotating file audit logger to a security domain. Syntax Example Verification In a browser, log in to your secured application. For example, to log in to the application created in Using a security domain to authenticate and authorize application users , navigate to http://localhost:8080/simple-webapp-example/secured and log in. Navigate to the directory configured to store the audit log. If you use the example commands in the procedure, the directory is EAP_HOME /standalone/log. Note that a file called periodic-file-audit.log is created. It contains the logs of the events triggered by logging in to the application. Example periodic-file-audit.log file Additional resources periodic-rotating-file-audit-log attributes 3.4. Enabling size rotating file audit logging in Elytron You can use the elytron subsystem to enable size rotating file audit logging for your standalone server or a server running as a managed domain. Size rotating file audit logging automatically rotates audit log files when the log file reaches a configured file size. Size rotating file audit logging is similar to default file audit logging, but the size rotating file audit logging contains additional attributes. When the log file size exceeds the limit defined by the rotate-size attribute, Elytron appends the suffix .1 to the end of the current file andcreates a new log file. For each existing log file, Elytron increments the suffix by one. For example, Elytron renames audit_log.1 to audit_log.2 . Elytron continues the increments until the log file amount reaches the maximum number of log files, as defined by max-backup-index . When a log file exceeds the max-backup-index value, Elytron removes the file. For example, if the max-backup-index defines "98" as the max-backup-index value, the audit_log.99 file would be over the limit. Prerequisites You have secured an application. For more information, see Creating an aggregate-realm in Elytron . Procedure Create a size rotating file audit log. Syntax Example Add the size rotating audit logger to a security domain. Syntax Example Verification In a browser, log in to your secured application. For example, to log in to the application created in Using a security domain to authenticate and authorize application users , navigate to http://localhost:8080/simple-webapp-example/secured and log in. Navigate to the directory configured to store the audit log. If you use the example commands in the procedure, the directory is EAP_HOME /standalone/log. Note that a file called size-file-audit.log is created. It contains the logs of the events triggered by logging in to the application. Example size-file-audit.log file Additional resources size-rotating-file-audit-log attributes 3.5. Enabling syslog audit logging in Elytron You can use the elytron subsystem to enable syslog audit logging for your standalone server or a server running as a managed domain. When you use syslog audit logging, you send the logging results to a syslog server, which provides more security options than logging to a local file. The syslog handler specifies parameters used to connect to a syslog server, such as the syslog server's host name and the port on which the syslog server listens. You can define multiple syslog handlers and activate them simultaneously. Supported log formats include RFC5424 and RFC3164 . Supported transmission protocols include UDP, TCP, and TCP with SSL. When you define a syslog for the first instance, the logger sends an INFORMATIONAL priority event containing the message to the syslog server, as demonstrated in the following example: <format> refers to the Request for Comments (RFC) format configured for the audit logging handler, which defaults to RFC5424 . Prerequisites You have secured an application. For more information, see Creating an aggregate-realm in Elytron . Procedure Add a syslog handler. Syntax You can also send logs to a syslog server over TLS: Syntax for syslog configuration to send logs over TLS Add the syslog audit logger to a security domain. Syntax Example Additional resources syslog-audit-log attributes Using a client-ssl-context The Syslog Protocol The BSD syslog Protocol 3.6. Using custom security event listeners in Elytron You can use Elytron to define a custom event listener. A custom event listener processes incoming security events. You can use the event listener for custom audit logging purposes, or you can use the event listener to authenticate users against your internal identity storage. Important The ability to add and remove modules by using the module management CLI command is provided as a Technology Preview feature only. The module command is not appropriate for use in a managed domain or when connecting with a remote management CLI. You must manually add or remove modules in a production environment. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features. Prerequisites You have secured an application. For more information, see Creating an aggregate-realm in Elytron . Procedure Create a class that implements the java.util.function.Consumer<org.wildfly.security.auth.server.event.SecurityEvent> interface. Example of creating a Java class that uses the specified interface: The Java class in the example prints a message whenever a user succeeds or fails authentication. Add the JAR file that provides the custom event listener as a module to JBoss EAP. The following is an example of the management CLI command that adds a custom event listener as a module to Elytron. Example of using the module command to add a custom event listener as a module to Elytron: Reference the custom event listener in the security domain. Example of referencing a custom event listener in ApplicationDomain : Restart the server. The event listener receives security events from the specified security domain. Additional resources Create a Custom Module Manually Remove a Custom Module Manually Add a Custom Component to Elytron

Commands:
/subsystem=elytron/file-audit-log= <audit_log_name> :add(path=" <path_to_log_file> ",format= <format_type> ,synchronized= <whether_to_log_immediately> )
/subsystem=elytron/file-audit-log=exampleFileAuditLog:add(path="file-audit.log",relative-to=jboss.server.log.dir,format=SIMPLE,synchronized=true)
/subsystem=elytron/security-domain= <security_domain_name> :write-attribute(name=security-event-listener,value= <audit_log_name> )
/subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleFileAuditLog)
2023-10-24 23:31:04,WARNING,{event=SecurityPermissionCheckSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true,permission=[type=org.wildfly.security.auth.permission.LoginPermission,actions=,name=]} 2023-10-24 23:31:04,WARNING,{event=SecurityAuthenticationSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true}
/subsystem=elytron/periodic-rotating-file-audit-log= <periodic_audit_log_name> :add(path=" <periodic_audit_log_filename> ",format= <record_format> ,synchronized= <whether_to_log_immediately> ,suffix=" <suffix_in_DateTimeFormatter_format> ")
/subsystem=elytron/periodic-rotating-file-audit-log=examplePreiodicFileAuditLog:add(path="periodic-file-audit.log",relative-to=jboss.server.log.dir,format=SIMPLE,synchronized=true,suffix="yyyy-MM-dd")
/subsystem=elytron/security-domain= <security_domain_name> :write-attribute(name=security-event-listener,value= <periodic_audit_log_name> )
/subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=examplePreiodicFileAuditLog)
2023-10-24 23:31:04,WARNING,{event=SecurityPermissionCheckSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true,permission=[type=org.wildfly.security.auth.permission.LoginPermission,actions=,name=]} 2023-10-24 23:31:04,WARNING,{event=SecurityAuthenticationSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true}
/subsystem=elytron/size-rotating-file-audit-log= <audit_log_name> :add(path="<path_to_log_file>",format= <record_format> ,synchronized= <whether_to_log_immediately> ,rotate-size=" <max_file_size_before_rotation> ",max-backup-index= <max_number_of_backup_files> )
/subsystem=elytron/size-rotating-file-audit-log=exampleSizeFileAuditLog:add(path="size-file-audit.log",relative-to=jboss.server.log.dir,format=SIMPLE,synchronized=true,rotate-size="10m",max-backup-index=10)
/subsystem=elytron/security-domain= <domain_size_logger> :write-attribute(name=security-event-listener,value= <audit_log_name> )
/subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleSizeFileAuditLog)
2023-10-24 23:31:04,WARNING,{event=SecurityPermissionCheckSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true,permission=[type=org.wildfly.security.auth.permission.LoginPermission,actions=,name=]} 2023-10-24 23:31:04,WARNING,{event=SecurityAuthenticationSuccessfulEvent,event-time=2023-10-24 23:31:04,security-identity=[name=user1,creation-time=2023-10-24 23:31:04],success=true}
"Elytron audit logging enabled with RFC format: <format>"
/subsystem=elytron/syslog-audit-log= <syslog_audit_log_name> :add(host-name= <record_host_name> ,port= <syslog_server_port_number> ,server-address= <syslog_server_address> ,format= <record_format> , transport= <transport_layer_protocol> )
/subsystem=elytron/syslog-audit-log= <syslog_audit_log_name> :add(transport=SSL_TCP,server-address= <syslog_server_address> ,port= <syslog_server_port_number> ,host-name= <record_host_name> ,ssl-context= <client_ssl_context> )
/subsystem=elytron/security-domain= <security_domain_name> :write-attribute(name=security-event-listener,value= <syslog_audit_log_name> )
/subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleSyslog)
public class MySecurityEventListener implements Consumer<SecurityEvent> { public void accept(SecurityEvent securityEvent) { if (securityEvent instanceof SecurityAuthenticationSuccessfulEvent) { System.err.printf("Authenticated user \"%s\"\n", securityEvent.getSecurityIdentity().getPrincipal()); } else if (securityEvent instanceof SecurityAuthenticationFailedEvent) { System.err.printf("Failed authentication as user \"%s\"\n", ((SecurityAuthenticationFailedEvent)securityEvent).getPrincipal()); } } }
/subsystem=elytron/custom-security-event-listener= <listener_name> :add(module= <module_name> , class-name= <class_name> )
/subsystem=elytron/security-domain= <domain_name> :write-attribute(name=security-event-listener, value= <listener_name> )
reload