Set Up Database Auditing (original) (raw)

Note

This feature is not available for any of the following deployments:

To learn more, see Limits.

Database auditing lets administrators track system activity for deployments with multiple users. Atlas administrators can select the actions, database users, Atlas roles, and LDAP groups that they want to audit. Atlas supports auditingmost of the documented system event actions, with the following limitation:

Important

Performing a Full Database Audit

Due to this limitation, you must use a combination of audit logs, the mongodb.log, and the Project Activity Feedto perform a full audit.

The authCheck event action logs authorization attempts by users trying to read from and write to databases in the clusters in your project. Atlas audits the following specific commands:

Atlas implements the authCheck event action as the following four separate actions:

Event Action Description
authChecksReadFailures authCheck event action for all failed reads with theauditAuthorizationSuccessparameter set to false. This event action is the default for read-related event actions.
authChecksReadAll authCheck event action for all reads, both sucesses and failures. This event action is the same as authChecksReadFailures, but with the auditAuthorizationSuccessparameter set to true.WARNING: If you enable auditAuthorizationSuccess, you might severely impact cluster performance. Enable this option with caution.
authChecksWriteFailures authCheck event action for all failed writes with theauditAuthorizationSuccessparameter set to false. This event action is the default for write-related event actions.
authChecksWriteAll authCheck event action for all writes, both successes and failures. This event action is the same asauthChecksWriteFailures, but with theauditAuthorizationSuccessparameter set to true.WARNING: If you enable auditAuthorizationSuccess, you might severely impact cluster performance. Enable this option with caution.

To learn about how MongoDB writes audit events to disk, seeAudit Guaranteein the MongoDB Manual.

To configure audit logs, you must haveProject Owner access to the project that you want to update or Organization Owner access to the organization that contains the project that you want to update.

To learn about recommendations for auditing and logging, including the events that we recommend auditing, seeRecommendations for Atlas Auditing and Logging in the Atlas Architecture Center.

Note

Use the following procedure to set up database auditing:

Warning

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.
  3. In the sidebar, click Advanced under the Security heading.
    The Advancedpage displays.

By default, Atlas logs the failed authentication attempts of both known and unknown users in the audit log of the primary node.

Alternatively, click Use Custom JSON Filter to manually enter an audit filteras a JSON string. For more information on configuring custom audit filters in Atlas, see Configure a Custom Auditing Filter.

Note

Deselecting the authenticate action prevents Atlas from auditing authentication failures.

Note

When selecting the authorization success granularityof auditing for the authCheck event action, Atlas does not support different selections for reads and writes. For example, you may not select Successes and Failures for authCheck Readsand Failures for authCheck Writes. If you select both authCheck Reads and authCheck Writes,Atlas automatically applies your selected granularity to both.

To retrieve the audit logs in Atlas, see MongoDB Logs. To retrieve the audit logs using the API, seeLogs.

Note

This feature is not available for any of the following deployments:

To learn more, see Limits.

Atlas supports specifying a JSON-formatted audit filter for customizing MongoDB Auditing.

Custom audit filters let users forgo the managed Atlas UI auditing filter builderin favor of hand-tailored granular control of event auditing.Atlas checks only that the custom filter uses valid JSON syntax, and doesn't validate or test the filter's functionality.

The audit filter document must resolve to a query that matches one or more fields in the audit event message. The filter document can use combinations of query operators and equality conditions to match the desired audit messages.

To view example auditing filters, seeExample Auditing Filters. To learn more about configuring MongoDB auditing filters, see Configure Audit Filter.

Important

Atlas uses a rolling upgrade strategy for enabling or updating audit configuration settings across all clusters in the Atlas project. Rolling upgrades require at least one election per replica set.

To learn more about testing application resilience to replica set elections, seeTest Primary Failover. To learn more about how Atlas provides high availability, seeAtlas High Availability.

Warning

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.
  3. In the sidebar, click Advanced under the Security heading.
    The Advancedpage displays.

Warning

Enabling Audit authorization successes can severely impact cluster performance. Enable this option with caution.

For audit filters specifying theauthCheck action type, the auditing system logs only authorization failures for any specified param.command by default. EnablingAudit authorization successes directs the auditing system to also log authorization successes. If you don't enableauditAuthorizationSuccess, your audit system can't log successful CRUD operations specified in theaction type. To learn more, see auditAuthorizationSuccess.

You can edit your filter at any time:

Warning

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

  3. In the sidebar, click Advanced under the Security heading.
    The Advancedpage displays.

  4. Under Database Auditing Configure Your Auditing Filter, clickUse Custom JSON Filter.

  5. Make the required changes.

  6. Click Save.

To return the auditing configuration for the specified project using the Atlas CLI, run the following command:


atlas auditing describe [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas auditing describe.

To view your custom auditing filter in the Atlas UI:

Warning

We're currently rolling out a new and improved navigation experience. If the following steps don't match your view in the Atlas UI, see the preview documentation.

  1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.
  3. In the sidebar, click Advanced under the Security heading.
    The Advancedpage displays.

Your custom auditing filter displays underDatabase Auditing.

Use the following example auditing filters for guidance in constructing your own filters.

Important

These examples are not intended for use in production environments, nor are they a replacement for familiarity with the MongoDB Auditing Documentation.


{

  "atype": "authenticate"

}



{

  "$or": [

    {

      "users": []

    },

    {

      "atype": "authenticate"

    }

  ]

}

Note

The authenticate action is required to log authentication failures from known and unknown users.


{

  "atype": "authenticate",

  "param": {

    "user": "myClusterAdministrator",

    "db": "admin",

    "mechanism": "SCRAM-SHA-256"

  }

}



{

  "atype": "authCheck",

  "param.command": {

    "$in": [

      "insert",

      "update",

      "delete"

    ]

  }

}