Audit Logging

Prerequisites

Enable SSL on the server. For more information, see Enable SSL.
Enable authentication on the server. For more information, see Authentication.

Event Categories and Supported Events

Audit logging lets you track and monitor user access and app usage and record critical events. By enabling audit logging, you can:

Track user access and ensure security by identifying unauthorized access.
Provide app developers with insights into app usage patterns, including user counts and usage duration.
Generate structured data that can be integrated with existing tools for further analysis.

Logging is organized into event categories, with each category comprising specific events that can be logged. In the configuration JSON, the event category is specified as event_category. The individual events supported by each category are listed under supported_events_doc, and the specific events you want to log for each category are selected from supported_events_doc and placed in the events field of the configuration JSON.

`event_category`	`supported_events_doc`	Description
`server`	`start`, `stop`	These events provide information about server operations, specifically when the server starts and stops.
`app`	`usage`, `upload`, `delete`	These events provide information about the duration of app usage and actions related to app management.
`authentication`	`login`, `logout`	These events provide information about user actions related to logging in and logging out.
`authorization`	`grant`, `denial`	These events capture a user's ability to upload or delete an app, based on whether authorization has been granted or denied.

Each event includes the user's name. If the userinfo.json file is configured in the webapps_private folder, the log file displays the value from the UserID key. If the userinfo.json file is not present, the log file instead uses the value from the displayName key found in the appConfig section of the webapps_authn.json file. For details, see Customize Web App Behavior Based on User.

The audit log files are written into a separate folder named auditlogs within the server logs directory. The default location for the server logs is:

Operating System	Logs Folder Location
Windows^®	`%ProgramData%\MathWorks\webapps\R2025a\logs`
Linux^®	`/local/MathWorks/webapps/R2025a/logs`
macOS	`/Library/Application Support/MathWorks/webapps/R2025a/logs`

Enable Audit Logging

To enable audit logging:

Create a file named auditlog.json and place it in the webapps_private folder, which is located within the config folder.

The webapps_private folder can be found in:

Operating System	Folder Location
Windows	`%ProgramData%\MathWorks\webapps\R2025a\config\webapps_private`
Linux	`/local/MathWorks/webapps/R2025a/config/webapps_private`
macOS	`/Library/Application Support/MathWorks/webapps/R2025a/config/webapps_private`

The JSON schema for auditlog.json is:

{
  "version": "<major>.<minor>.<patch>",
  "log_file_max_size": "A numeric value representing the maximum size of a log file in MB",
  "log_files_max_num": "A numeric value representing the maximum number of log files to retain",
  "event_categories": [
    {
      "event_category": "server",
      "enable": "<all | none | specified>",
      "events": ["<start | stop>"],
      "supported_events_doc": "<start, stop>"
    },
    {
      "event_category": "app",
      "enable": "<all | none | specified>",
      "events": ["<usage | upload | delete>"],
      "supported_events_doc": "<usage, upload, delete>"
    },
    {
      "event_category": "authentication",
      "enable": "<all | none | specified>",
      "events": ["<login | logout>"],
      "supported_events_doc": "<login, logout>"
    },
    {
      "event_category": "authorization",
      "enable": "<all | none | specified>",
      "events": ["<grant | denial>"],
      "supported_events_doc": "<grant, denial>"
    }
  ]
}

version: Specify the version of the JSON schema. The default value for R2025a is 1.0.0.
log_file_max_size: Specify a numeric value representing the maximum size of a log file in MB. For example, to set the maximum log file size to 10 MB, use: 10.
log_files_max_num: Specify a numeric value representing the maximum number of log files to retain. For example, to retain up to 20 log files, use: 20.
event_categories: Specify different event categories supported by audit logging in the event_categories array. Currently, the supported event categories are: server, app, authentication, and authorization.
enable: Specify whether to enable or disable the current event category for audit logging using the enable field. The supported values are: all, none, and specified. When specified is chosen, only the events listed in the events field are logged. For example, to log all events in a category, use: "all".
event_category: Specify the type of events to be logged using the event_category field. The supported categories include server, app, authentication, and authorization. For example, to specify logging for server events, use: "server".
events: Specify the particular events to log by using the events array. The values must be specified as an array of strings, each representing an event, or as a single comma-separated string listing those events. This array is relevant only when the enable field is set to specified, ensuring that only the events listed here are recorded in the audit log. For example, to log start and stop events, use: ["start", "stop"].
supported_events_doc: Specify the supported events for each event category using the supported_events_doc field. This information helps users determine which events can be added to the events array for logging purposes. For example, to document supported server events like start and stop, use: "start, stop".

Example `auditlog.json` File

{
  "version": "1.0.0",
  "log_file_max_size": 100,
  "log_files_max_num": 5,
  "event_categories": [
    {
      "event_category": "server",
      "enable": "specified",
      "events": ["start", "stop"],
      "supported_events_doc": "start, stop"
    },
    {
      "event_category": "app",
      "enable": "all",
      "events": ["usage", "upload", "delete"],
      "supported_events_doc": "usage, upload, delete"
    },
    {
      "event_category": "authentication",
      "enable": "specified",
      "events": ["login"],
      "supported_events_doc": "login, logout"
    },
    {
      "event_category": "authorization",
      "enable": "specified",
      "events": ["grant"],
      "supported_events_doc": "grant, denial"
    }
  ]
}

Sample Log File

{ "timestamp": "2024-10-14 13:16:08", "category": "server", "event": "start" }
{ "timestamp": "2024-10-14 13:16:26", "category": "authentication", "event": "login", "user": "cinderella" }
{ "timestamp": "2024-10-14 13:20:59", "category": "authorization", "event": "grant", "action": "app_upload", "user": "alice" }
{ "timestamp": "2024-10-14 13:26:44", "category": "app", "event": "delete", "app_name": "app1.ctf" }
{ "timestamp": "2024-10-14 13:29:19", "category": "authorization", "event": "grant", "action": "app_upload", "user": "raya" }
{ "timestamp": "2024-10-14 13:29:24", "category": "app", "event": "delete", "app_name": "app2.ctf" }
{ "timestamp": "2024-10-14 13:29:49", "category": "authorization", "event": "grant", "action": "app_upload", "user": "cali" }
{ "timestamp": "2024-10-14 13:30:10", "category": "app", "event": "upload", "app_name": "app3.ctf" }
{ "timestamp": "2024-10-14 13:30:30", "category": "server", "event": "stop" }
{ "timestamp": "2024-10-14 13:31:00", "category": "app", "event": "usage", "app_name": "app4", "duration": "310" }

Authentication Events

These events provide information about user actions related to logging in. In the log, only "login" actions are recorded. For example:

{"timestamp": "2024-10-14 13:16:26", "category": "authentication", "event": "login", "user": "cinderella"}

This log entry indicates that at 1:16 PM on October 14, 2024, the user "cinderella" successfully logged into the system.

Authorization Events

These events capture actions related to granting permissions to users for app-related tasks. The configuration specifies "enable": "specified" for this category, focusing on the "grant" action to track which users were authorized to upload apps. For example:

{"timestamp": "2024-10-14 13:20:59", "category": "authorization", "event": "grant", "action": "app_upload", "user": "alice"}

This log entry shows that user "alice" was granted permission to upload apps.

App Events

These events provide information about actions such as uploading, deleting, and using apps. The configuration specifies "enable": "all" for the "app" category, capturing all app-related activities. For example:

Delete

{"timestamp": "2024-10-14 13:26:44", "category": "app", "event": "delete", "app_name": "app1.ctf"}

This entry indicates that "app1.ctf" was deleted.

Upload

{"timestamp": "2024-10-14 13:30:10", "category": "app", "event": "upload", "app_name": "app3.ctf"}

This entry indicates that "app3.ctf" was uploaded.

Usage

{"timestamp": "2024-10-14 13:31:00", "category": "app", "event": "usage", "app_name": "app4", "duration": "310"}

This entry indicates that "app4" was used for 310 seconds.

Server Events

These events provide information about server operations, specifically when the server starts and stops. The configuration specifies "enable": "all" for the "server" category, capturing both "start" and "stop" actions. For example:

Start

{"timestamp": "2024-10-14 13:16:08", "category": "server", "event": "start"}

This entry indicates that the server started at 1:16 PM on October 14, 2024.

Stop

{"timestamp": "2024-10-14 13:30:30", "category": "server", "event": "stop"}

This entry indicates that the server stopped at 1:30 PM on the same day.

Audit Logging

Prerequisites

Event Categories and Supported Events

Enable Audit Logging

Example `auditlog.json` File

Sample Log File

Authentication Events

Authorization Events

App Events

Server Events

See Also

Topics

Audit Logging

Prerequisites

Event Categories and Supported Events

Enable Audit Logging

Example auditlog.json File

Sample Log File

Authentication Events

Authorization Events

App Events

Server Events

See Also

Topics

Example `auditlog.json` File