From 2ea8f52ccbb9e6a6f06aec83bd9ae10ee8273a47 Mon Sep 17 00:00:00 2001
From: Anastasia Alexandrova <anastasia.alexandrova@percona.com>
Date: Tue, 9 Apr 2024 17:34:41 +0200
Subject: [PATCH] PSMDB-1434 Updated audit log doc (#834)

modified:   docs/audit-logging.md
modified:   docs/enable-auth.md
---
 docs/audit-logging.md | 64 +++++++++++++++++++++++++++++++++++++++----
 docs/enable-auth.md   |  2 +-
 2 files changed, 60 insertions(+), 6 deletions(-)

diff --git a/docs/audit-logging.md b/docs/audit-logging.md
index bd5c495f9..1b54916e0 100644
--- a/docs/audit-logging.md
+++ b/docs/audit-logging.md
@@ -205,13 +205,11 @@ on all the collections in the `test` database:
 
 ## Enabling auditing of authorization success
 
-By default, only authorization failures for the `authCheck` action
-are logged by the audit system. `authCheck` is for authorization by
-role-based access control, it does not concern authentication at logins.
+By default, the audit system logs only authorization failures for the `authCheck` action. The `authCheck` action refers to the operations a user is or is not authorized to perform on the server according to the privileges outlined in the roles assigned to the user.
 
 To enable logging of authorization successes,
 set the `auditAuthorizationSuccess` parameter to `true`. Audit events
-will then be triggered by every command, including CRUD ones.
+will then be triggered by every command that requires authorization, including CRUD ones.
 
 !!! warning 
 
@@ -235,4 +233,60 @@ You can also add it to the configuration file as follows:
 ```yaml
 setParameter:
   auditAuthorizationSuccess: true
-```
\ No newline at end of file
+```
+
+??? example "Example of the audit message"
+
+    ```json
+    {
+      "atype": "authCheck",
+      "ts": {
+        "$date": "2024-03-13T06:28:04.631-04:00"
+      },
+      "local": {
+        "ip": "172.17.0.2",
+        "port": 20040
+      },
+      "remote": {
+        "ip": "127.0.0.1",
+        "port": 52128
+      },
+      "users": [
+        {
+          "user": "admin",
+          "db": "admin"
+        }
+      ],
+      "roles": [
+        {
+          "role": "clusterAdmin",
+          "db": "admin"
+        },
+        {
+          "role": "readWriteAnyDatabase",
+          "db": "admin"
+        },
+        {
+          "role": "userAdminAnyDatabase",
+          "db": "admin"
+        }
+      ],
+      "param": {
+        "command": "insert",
+        "ns": "audit_authz_insert.foo",
+        "args": {
+          "insert": "foo",
+          "ordered": true,
+          "lsid": {
+            "id": {
+              "$binary": "nfnnHQo0RDOtI6722FlP5w==",
+              "$type": "04"
+            }
+          },
+          "$db": "audit_authz_insert"
+        }
+      },
+      "result": 0
+    }
+    ```
+
diff --git a/docs/enable-auth.md b/docs/enable-auth.md
index 428c75541..403467af9 100644
--- a/docs/enable-auth.md
+++ b/docs/enable-auth.md
@@ -35,7 +35,7 @@ To enable access control manually:
 2. Run the following command on the `admin` database:
 
     ```{.javascript data-prompt=">"}
-    > db.createUser({user: 'USER', pwd: 'PASSWORD', roles: ['root'] });
+    > db.createUser({user: 'USER', pwd: 'PASSWORD', roles: ['dbAdmin'] });
     ```
 
 3. Restart the `mongod` service: