Audit Service
Introduction #
Many organizations have the need to produce a audit trail of user actions. In many countries this is mandated by law and the data might need to be stored for long time. Audit Service provides a pluggable way of storing the audit trail from Liferay Portal and plugins. The information is then processed by Audit Service plugin that can store the information into log files or database or both.
Architecture #
Audit Service leverages Liferays Lightweight Message Bus and Plugin architecture. The service itself is a plugin that handles the processing and logging of the audit messages sent through the Message Bus. Any plugin can then produce audit messages to the audit message bus destination. A set of audit message producers is implanted as a hook plugin to provide information on login, logout, user information changes, user role changes etc.
Audit Event Message #
The audit event message is pushed to the message bus in JSON format allowing the stored data to be easily extended. The table below describes the message fields and their data type.
| Field | Type | Description | |
|---|---|---|---|
| companyId | LONG | Portal instance companyId | |
| userId | LONG | User ID of user performing the action | |
| userName | STRING | Username of the user performing the action | |
| className | STRING | Target object class name id | |
| classPK | STRING | Target object primary key | |
| type | STRING | Action type | |
| sessionID | STRING | HTTP Session ID | |
| clientIP | STRING | Remote client IP address | |
| serverIP | STRING | Originating server IP | |
| timestamp | DATETIME | Event timestamp | |
| additionalInfo | STRING | Additional information for the action in JSON format |
Audit Plugin #
Audit plugin registers a new destination (liferay/audit) and listener to the message bus. The listener dispatches the messages to the audit service for processing. Different processors can be registered with the audit service. By default the plugin comes with a Database Processor and Log4J Processor. Processors can be either be global or for a specific event type. For instance database processor would be global but Log processor would be only for login events.
Processors #
Database Processor #
Database processor stores all events to database for later analysis. This information could be searched through a portlet. The database size can quite quick become huge if lot of information is logged. Then an archival or cleanup task should be used to keep the table size reasonable.
Log4J Processor #
Log4J processor logs the event information using Log4J logging framework. With Log4J configuration the information can be directed to a log file or even to another system through JMS, SMTP or SysLog. If the information is logged to a log file the file rolling and archival can be configured through log4j configuration file. The default log formatter is CSV formatter that formats the messages in CSV for easy importing into Excel. Also a JSON formatter is provided and can be configured in WEB-INF/classes/META-INF/ext-spring.xml. With property audit.log.csv.columns you can control which fields from audit message are logged and what their order is. By default all fields are logged in the order defined in Table 1.
Audit Reports #
Audit plugin comes with a reporting portlet. It allows you to search and browse the audit events stored into database.
Audit Hooks #
Liferay provides a lot of places to hook for creating custom audit hooks. By default audit service comes with following hooks to provide information of services like authentication, authorization and user management:
| Hook | Event Type | Description | |||||
| Login | login | Logs all logins. Implemented by com.liferay.portal.audit.events.authentication.LoginAudit | |||||
| Logout | logout | Logs all logouts. Implemented by com.liferay.portal.audit.events.authentication.LogoutAudit | |||||
| Login Failure | login-failure | Logs all login failures. Implemented by com.liferay.portal.audit.events.authentication.LoginFailureAudit | |||||
| Impersonation | impersonate | Logs when impersonation is started. Implemented by com.liferay.portal.audit.events.user.ImpersonationAudit | |||||
| Role create | role-create | Logs removal of a role. Implemented by com.liferay.portal.audit.events.user.RoleModificationAudit | |||||
| Role remove | role-remove | Logs removal of a role. Implemented by com.liferay.portal.audit.events.user.RoleModificationAudit | |||||
| Role update | role | Logs update of a role. Implemented by com.liferay.portal.audit.events.user.RoleModificationAudit | |||||
| Role grant | role-grant | Logs role assignment to User, User Group, Organization or Community. Implemented by com.liferay.portal.audit.events.user.RoleModificationAudit for regular roles and com.liferay.portal.audit.events.user.UserGroupRoleModificationAudit for Organization and Community roles. value.object.listener.com.liferay.portal.model.Role=com.liferay.portal.audit.events.user.RoleModificationAudit | |||||
| Role revoke | role-revoke | Logs role removal to User, User Group, Organization or Community. Implemented by com.liferay.portal.audit.events.user.RoleModificationAudit for regular roles and com.liferay.portal.audit.events.user.UserGroupRoleModificationAudit for Organization and Community roles. value.object.listener.com.liferay.portal.model.Role=com.liferay.portal.audit.events.user.RoleModificationAudit | |||||
| User create | user-create | ||||||
| User remove | user-remove | ||||||
| User update | profile | ||||||
| User contact update | profile | ||||||
| User address update | profile | ||||||
| User Group create | usergroup-create | ||||||
| User Group remove | usergroup-delete | ||||||
| User Group update | usergroup-update |
Installation and Configuration Reference #
For auditing to work you need to install audit-portlet and audit-hook from plugins incubation and you need to use the portal trunk until 5.3 is released.
Future Improvements #
Archiving #
Database can quickly fill up with audit events if all the user activities are audited and thus a archiving solution needs to be developed.
More audit hooks #
More hooks need to developed for being able to audit all the user activities on the portal.
