Search
SupportConsoleDevelopersStart a trialContact

Chapter 3. Configuring audit logging in Elytron

download PDF

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.

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

Procedure

  1. Create a file audit log.

    Syntax

    /subsystem=elytron/file-audit-log=<audit_log_name>:add(path="<path_to_log_file>",format=<format_type>,synchronized=<whether_to_log_immediately>)

    Example

    /subsystem=elytron/file-audit-log=exampleFileAuditLog:add(path="file-audit.log",relative-to=jboss.server.log.dir,format=SIMPLE,synchronized=true)

  2. Add the file audit log to a security domain.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:write-attribute(name=security-event-listener,value=<audit_log_name>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleFileAuditLog)

Verification

  1. 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.

  2. 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

    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}

Additional resources

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

Procedure

  1. Create a periodic rotating file audit log.

    Syntax

    /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>")

    Example

    /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")

  2. Add the periodic rotating file audit logger to a security domain.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:write-attribute(name=security-event-listener,value=<periodic_audit_log_name>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=examplePreiodicFileAuditLog)

Verification

  1. 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.

  2. 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

    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}

Additional resources

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

Procedure

  1. Create a size rotating file audit log.

    Syntax

    /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>)

    Example

    /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)

  2. Add the size rotating audit logger to a security domain.

    Syntax

    /subsystem=elytron/security-domain=<domain_size_logger>:write-attribute(name=security-event-listener,value=<audit_log_name>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleSizeFileAuditLog)

Verification

  1. 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.

  2. 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

    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}

Additional resources

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: 

"Elytron audit logging enabled with RFC format: <format>"

<format> refers to the Request for Comments (RFC) format configured for the audit logging handler, which defaults to RFC5424.

Prerequisites

Procedure

  1. Add a syslog handler.

    Syntax

    /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>)

    You can also send logs to a syslog server over TLS:

    Syntax for syslog configuration to send logs over TLS

    /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>)

  2. Add the syslog audit logger to a security domain.

    Syntax

    /subsystem=elytron/security-domain=<security_domain_name>:write-attribute(name=security-event-listener,value=<syslog_audit_log_name>)

    Example

    /subsystem=elytron/security-domain=exampleSecurityDomain:write-attribute(name=security-event-listener,value=exampleSyslog)

Additional resources

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

Procedure

  1. 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:

    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());
        }
    }
}

    The Java class in the example prints a message whenever a user succeeds or fails authentication.

  2. 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:

    /subsystem=elytron/custom-security-event-listener=<listener_name>:add(module=<module_name>, class-name=<class_name>)

  3. Reference the custom event listener in the security domain.

    Example of referencing a custom event listener in ApplicationDomain:

    /subsystem=elytron/security-domain=<domain_name>:write-attribute(name=security-event-listener, value=<listener_name>)

  4. Restart the server. 

    $ reload

    The event listener receives security events from the specified security domain.

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.