New module API event for tracking authentication attempts (#2237)

rjd15372 · web-flow · commit b44de37b7d2a · 2025-09-01T15:02:26.000+01:00
In this commit we introduce a new module API event called `ValkeyModuleEvent_AuthenticationAttempt` to track successful/failed authentication attempts. This event will fill a struct, called `ValkeyModuleAuthenticationInfo`, with the client ID of the connection, the username, the module name that handle the authentication event, and the result of the authentication attempt. Fixes: #2211 --------- Signed-off-by: Ricardo Dias <ricardo.dias@percona.com>
diff --git a/src/acl.c b/src/acl.c
@@ -1458,16 +1458,25 @@ void addAuthErrReply(client *c, robj *err) {
  *
  * The return value is AUTH_OK on success (valid username / password pair) & AUTH_ERR otherwise. */
 static int checkPasswordBasedAuth(client *c, robj *username, robj *password) {
+    int result;
+
     if (ACLCheckUserCredentials(username, password) == C_OK) {
         user *user = ACLGetUserByName(username->ptr, sdslen(username->ptr));
         clientSetUser(c, user, 1);
         moduleNotifyUserChanged(c);
-        return AUTH_OK;
+        result = AUTH_OK;
     } else {
         addACLLogEntry(c, ACL_DENIED_AUTH, (c->flag.multi) ? ACL_LOG_CTX_MULTI : ACL_LOG_CTX_TOPLEVEL, 0, username->ptr,
                        NULL);
-        return AUTH_ERR;
+        result = AUTH_ERR;
     }
+
+    moduleFireAuthenticationEvent(c->id,
+                                  username->ptr,
+                                  NULL,
+                                  result == AUTH_OK);
+
+    return result;
 }
 
 /* Attempt authenticating the user - first through module based authentication,
diff --git a/src/module.c b/src/module.c
@@ -8012,7 +8012,7 @@ void moduleUnregisterAuthCBs(ValkeyModule *module) {
 
 /* Search for & attempt next module auth callback after skipping the ones already attempted.
  * Returns the result of the module auth callback. */
-int attemptNextAuthCb(client *c, robj *username, robj *password, robj **err) {
+static int attemptNextAuthCb(client *c, robj *username, robj *password, robj **err) {
     int handle_next_callback = (!c->module_data || c->module_data->module_auth_ctx == NULL);
     ValkeyModuleAuthCtx *cur_auth_ctx = NULL;
     listNode *ln;
@@ -8047,7 +8047,7 @@ int attemptNextAuthCb(client *c, robj *username, robj *password, robj **err) {
  * auth operation.
  * Otherwise, we attempt the auth reply callback & the free priv data callback, update fields and
  * return the result of the reply callback. */
-int attemptBlockedAuthReplyCallback(client *c, robj *username, robj *password, robj **err) {
+static int attemptBlockedAuthReplyCallback(client *c, robj *username, robj *password, robj **err) {
     int result = VALKEYMODULE_AUTH_NOT_HANDLED;
     if (!c->module_data || !c->module_data->module_blocked_client) return result;
     ValkeyModuleBlockedClient *bc = (ValkeyModuleBlockedClient *)c->module_data->module_blocked_client;
@@ -8091,17 +8091,44 @@ int checkModuleAuthentication(client *c, robj *username, robj *password, robj **
         serverAssert(result == VALKEYMODULE_AUTH_HANDLED);
         return AUTH_BLOCKED;
     }
+
+    ValkeyModuleAuthCtx *auth_ctx = c->module_data ? c->module_data->module_auth_ctx : NULL;
+
     if (c->module_data) c->module_data->module_auth_ctx = NULL;
     if (result == VALKEYMODULE_AUTH_NOT_HANDLED) {
         c->flag.module_auth_has_result = 0;
         return AUTH_NOT_HANDLED;
     }
 
+    int auth_result = AUTH_ERR;
+
     if (c->flag.module_auth_has_result) {
         c->flag.module_auth_has_result = 0;
-        if (c->flag.authenticated) return AUTH_OK;
+        if (c->flag.authenticated) {
+            auth_result = AUTH_OK;
+        }
     }
-    return AUTH_ERR;
+
+    const char *module_name = auth_ctx ? auth_ctx->module->name : NULL;
+    moduleFireAuthenticationEvent(c->id,
+                                  username->ptr,
+                                  module_name,
+                                  auth_result == AUTH_OK);
+
+    return auth_result;
+}
+
+void moduleFireAuthenticationEvent(uint64_t client_id,
+                                   const char *username,
+                                   const char *module_name,
+                                   int is_granted) {
+    ValkeyModuleAuthenticationInfo info = VALKEYMODULE_AUTHENTICATIONINFO_INITIALIZER_V1;
+    info.client_id = client_id;
+    info.username = username;
+    info.module_name = module_name;
+    info.result = is_granted ? VALKEYMODULE_AUTH_RESULT_GRANTED
+                             : VALKEYMODULE_AUTH_RESULT_DENIED;
+    moduleFireServerEvent(VALKEYMODULE_EVENT_AUTHENTICATION_ATTEMPT, 0, &info);
 }
 
 /* This function is called from module.c in order to check if a module
@@ -11480,24 +11507,25 @@ void ModuleForkDoneHandler(int exitcode, int bysignal) {
  * a data structure associated with it. We use MAX_UINT64 on purpose,
  * in order to pass the check in ValkeyModule_SubscribeToServerEvent. */
 static uint64_t moduleEventVersions[] = {
-    VALKEYMODULE_REPLICATIONINFO_VERSION,  /* VALKEYMODULE_EVENT_REPLICATION_ROLE_CHANGED */
-    -1,                                    /* VALKEYMODULE_EVENT_PERSISTENCE */
-    VALKEYMODULE_FLUSHINFO_VERSION,        /* VALKEYMODULE_EVENT_FLUSHDB */
-    -1,                                    /* VALKEYMODULE_EVENT_LOADING */
-    VALKEYMODULE_CLIENTINFO_VERSION,       /* VALKEYMODULE_EVENT_CLIENT_CHANGE */
-    -1,                                    /* VALKEYMODULE_EVENT_SHUTDOWN */
-    -1,                                    /* VALKEYMODULE_EVENT_REPLICA_CHANGE */
-    -1,                                    /* VALKEYMODULE_EVENT_PRIMARY_LINK_CHANGE */
-    VALKEYMODULE_CRON_LOOP_VERSION,        /* VALKEYMODULE_EVENT_CRON_LOOP */
-    VALKEYMODULE_MODULE_CHANGE_VERSION,    /* VALKEYMODULE_EVENT_MODULE_CHANGE */
-    VALKEYMODULE_LOADING_PROGRESS_VERSION, /* VALKEYMODULE_EVENT_LOADING_PROGRESS */
-    VALKEYMODULE_SWAPDBINFO_VERSION,       /* VALKEYMODULE_EVENT_SWAPDB */
-    -1,                                    /* VALKEYMODULE_EVENT_REPL_BACKUP */
-    -1,                                    /* VALKEYMODULE_EVENT_FORK_CHILD */
-    -1,                                    /* VALKEYMODULE_EVENT_REPL_ASYNC_LOAD */
-    -1,                                    /* VALKEYMODULE_EVENT_EVENTLOOP */
-    -1,                                    /* VALKEYMODULE_EVENT_CONFIG */
-    VALKEYMODULE_KEYINFO_VERSION,          /* VALKEYMODULE_EVENT_KEY */
+    VALKEYMODULE_REPLICATIONINFO_VERSION,     /* VALKEYMODULE_EVENT_REPLICATION_ROLE_CHANGED */
+    -1,                                       /* VALKEYMODULE_EVENT_PERSISTENCE */
+    VALKEYMODULE_FLUSHINFO_VERSION,           /* VALKEYMODULE_EVENT_FLUSHDB */
+    -1,                                       /* VALKEYMODULE_EVENT_LOADING */
+    VALKEYMODULE_CLIENTINFO_VERSION,          /* VALKEYMODULE_EVENT_CLIENT_CHANGE */
+    -1,                                       /* VALKEYMODULE_EVENT_SHUTDOWN */
+    -1,                                       /* VALKEYMODULE_EVENT_REPLICA_CHANGE */
+    -1,                                       /* VALKEYMODULE_EVENT_PRIMARY_LINK_CHANGE */
+    VALKEYMODULE_CRON_LOOP_VERSION,           /* VALKEYMODULE_EVENT_CRON_LOOP */
+    VALKEYMODULE_MODULE_CHANGE_VERSION,       /* VALKEYMODULE_EVENT_MODULE_CHANGE */
+    VALKEYMODULE_LOADING_PROGRESS_VERSION,    /* VALKEYMODULE_EVENT_LOADING_PROGRESS */
+    VALKEYMODULE_SWAPDBINFO_VERSION,          /* VALKEYMODULE_EVENT_SWAPDB */
+    -1,                                       /* VALKEYMODULE_EVENT_REPL_BACKUP */
+    -1,                                       /* VALKEYMODULE_EVENT_FORK_CHILD */
+    -1,                                       /* VALKEYMODULE_EVENT_REPL_ASYNC_LOAD */
+    -1,                                       /* VALKEYMODULE_EVENT_EVENTLOOP */
+    -1,                                       /* VALKEYMODULE_EVENT_CONFIG */
+    VALKEYMODULE_KEYINFO_VERSION,             /* VALKEYMODULE_EVENT_KEY */
+    VALKEYMODULE_AUTHENTICATION_INFO_VERSION, /* VALKEYMODULE_EVENT_AUTHENTICATION_ATTEMPT */
 };
 
 /* Register to be notified, via a callback, when the specified server event
@@ -11758,7 +11786,7 @@ static uint64_t moduleEventVersions[] = {
  *     * `VALKEYMODULE_SUBEVENT_EVENTLOOP_BEFORE_SLEEP`
  *     * `VALKEYMODULE_SUBEVENT_EVENTLOOP_AFTER_SLEEP`
  *
- * * ValkeyModule_Event_Config
+ * * ValkeyModuleEvent_Config
  *
  *     Called when a configuration event happens
  *     The following sub events are available:
@@ -11772,7 +11800,7 @@ static uint64_t moduleEventVersions[] = {
  *                                    // name of each modified configuration item
  *         uint32_t num_changes;      // The number of elements in the config_names array
  *
- * * ValkeyModule_Event_Key
+ * * ValkeyModuleEvent_Key
  *
  *     Called when a key is removed from the keyspace. We can't modify any key in
  *     the event.
@@ -11788,6 +11816,22 @@ static uint64_t moduleEventVersions[] = {
  *
  *         ValkeyModuleKey *key;    // Key name
  *
+ * * ValkeyModuleEvent_AuthenticationAttempt
+ *
+ *     Called when an authentication attempt is made, either successful or not.
+ *
+ *     The data pointer can be casted to a ValkeyModuleAuthenticationInfo
+ *     structure with the following fields:
+ *
+ *         uint64_t client_id;      // Client ID.
+ *         const char *username;    // Username used for authentication.
+ *         const char *module_name; // Name of the module that is handling the
+ *                                  // authentication. It is NULL if the
+ *                                  // authentication is handled by the core.
+ *         ValkeyModuleAuthenticationResult result;   // Result of the authentication:
+ *                                                    // VALKEYMODULE_AUTH_RESULT_GRANTED or
+ *                                                    // VALKEYMODULE_AUTH_RESULT_DENIED
+ *
  * The function returns VALKEYMODULE_OK if the module was successfully subscribed
  * for the specified event. If the API is called from a wrong context or unsupported event
  * is given then VALKEYMODULE_ERR is returned. */
@@ -11937,6 +11981,8 @@ void moduleFireServerEvent(uint64_t eid, int subid, void *data) {
                 selectDb(ctx.client, info->dbnum);
                 moduleInitKey(&key, &ctx, info->key, info->value, info->mode);
                 moduledata = &ki;
+            } else if (eid == VALKEYMODULE_EVENT_AUTHENTICATION_ATTEMPT) {
+                moduledata = data;
             }
 
             el->module->in_hook++;
diff --git a/src/module.h b/src/module.h
@@ -230,5 +230,7 @@ void moduleDefragGlobals(void);
 void *moduleGetHandleByName(char *modulename);
 int moduleIsModuleCommand(void *module_handle, struct serverCommand *cmd);
 void freeClientModuleData(client *c);
+int checkModuleAuthentication(client *c, robj *username, robj *password, robj **err);
+void moduleFireAuthenticationEvent(uint64_t client_id, const char *username, const char *module_name, int is_granted);
 
 #endif /* _MODULE_H_ */
diff --git a/src/modules/hellohook.c b/src/modules/hellohook.c
@@ -71,6 +71,15 @@ void flushdbCallback(ValkeyModuleCtx *ctx, ValkeyModuleEvent e, uint64_t sub, vo
     }
 }
 
+void authenticationAttemptCallback(ValkeyModuleCtx *ctx, ValkeyModuleEvent e, uint64_t sub, void *data) {
+    VALKEYMODULE_NOT_USED(ctx);
+    VALKEYMODULE_NOT_USED(e);
+
+    ValkeyModuleAuthenticationInfo *ai = data;
+    printf("Authentication attempt for client #%llu with username=%s module=%s success=%d\n",
+           (unsigned long long)ai->client_id, ai->username, ai->module_name, ai->result == VALKEYMODULE_AUTH_RESULT_GRANTED);
+}
+
 /* This function must be present on each module. It is used in order to
  * register the commands into the server. */
 int ValkeyModule_OnLoad(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc) {
@@ -81,5 +90,6 @@ int ValkeyModule_OnLoad(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int arg
 
     ValkeyModule_SubscribeToServerEvent(ctx, ValkeyModuleEvent_ClientChange, clientChangeCallback);
     ValkeyModule_SubscribeToServerEvent(ctx, ValkeyModuleEvent_FlushDB, flushdbCallback);
+    ValkeyModule_SubscribeToServerEvent(ctx, ValkeyModuleEvent_AuthenticationAttempt, authenticationAttemptCallback);
     return VALKEYMODULE_OK;
 }
diff --git a/src/server.h b/src/server.h
@@ -3198,7 +3198,6 @@ typedef enum {
 
 int ACLCheckUserCredentials(robj *username, robj *password);
 int ACLAuthenticateUser(client *c, robj *username, robj *password, robj **err);
-int checkModuleAuthentication(client *c, robj *username, robj *password, robj **err);
 void addAuthErrReply(client *c, robj *err);
 unsigned long ACLGetCommandID(sds cmdname);
 user *ACLGetUserByName(const char *name, size_t namelen);
diff --git a/src/valkeymodule.h b/src/valkeymodule.h
@@ -522,7 +522,8 @@ typedef void (*ValkeyModuleEventLoopOneShotFunc)(void *user_data);
 #define VALKEYMODULE_EVENT_EVENTLOOP 15
 #define VALKEYMODULE_EVENT_CONFIG 16
 #define VALKEYMODULE_EVENT_KEY 17
-#define _VALKEYMODULE_EVENT_NEXT 18 /* Next event flag, should be updated if a new event added. */
+#define VALKEYMODULE_EVENT_AUTHENTICATION_ATTEMPT 18
+#define _VALKEYMODULE_EVENT_NEXT 19 /* Next event flag, should be updated if a new event added. */
 
 typedef struct ValkeyModuleEvent {
     uint64_t id;      /* VALKEYMODULE_EVENT_... defines. */
@@ -579,7 +580,8 @@ static const ValkeyModuleEvent ValkeyModuleEvent_ReplicationRoleChanged = {VALKE
                                ValkeyModuleEvent_ForkChild = {VALKEYMODULE_EVENT_FORK_CHILD, 1},
                                ValkeyModuleEvent_EventLoop = {VALKEYMODULE_EVENT_EVENTLOOP, 1},
                                ValkeyModuleEvent_Config = {VALKEYMODULE_EVENT_CONFIG, 1},
-                               ValkeyModuleEvent_Key = {VALKEYMODULE_EVENT_KEY, 1};
+                               ValkeyModuleEvent_Key = {VALKEYMODULE_EVENT_KEY, 1},
+                               ValkeyModuleEvent_AuthenticationAttempt = {VALKEYMODULE_EVENT_AUTHENTICATION_ATTEMPT, 1};
 
 /* Those are values that are used for the 'subevent' callback argument. */
 #define VALKEYMODULE_SUBEVENT_PERSISTENCE_RDB_START 0
@@ -781,6 +783,25 @@ typedef struct ValkeyModuleKeyInfo {
 
 #define ValkeyModuleKeyInfo ValkeyModuleKeyInfoV1
 
+#define VALKEYMODULE_AUTHENTICATION_INFO_VERSION 1
+
+typedef enum {
+    VALKEYMODULE_AUTH_RESULT_GRANTED = 0, /* Authentication succeeded. */
+    VALKEYMODULE_AUTH_RESULT_DENIED = 1,  /* Authentication failed. */
+} ValkeyModuleAuthenticationResult;
+
+typedef struct ValkeyModuleAuthenticationInfo {
+    uint64_t version;                        /* Version of this structure for ABI compat. */
+    uint64_t client_id;                      /* Client ID. */
+    const char *username;                    /* Username used for authentication. */
+    const char *module_name;                 /* Name of the module that is handling the authentication. */
+    ValkeyModuleAuthenticationResult result; /* Result of the authentication */
+} ValkeyModuleAuthenticationInfoV1;
+
+#define ValkeyModuleAuthenticationInfo ValkeyModuleAuthenticationInfoV1
+
+#define VALKEYMODULE_AUTHENTICATIONINFO_INITIALIZER_V1 {.version = 1}
+
 typedef enum {
     VALKEYMODULE_ACL_LOG_AUTH = 0, /* Authentication failure */
     VALKEYMODULE_ACL_LOG_CMD,      /* Command authorization failure */
diff --git a/tests/modules/hooks.c b/tests/modules/hooks.c
@@ -365,6 +365,19 @@ void keyInfoCallback(ValkeyModuleCtx *ctx, ValkeyModuleEvent e, uint64_t sub, vo
     }
 }
 
+void authAttemptCallback(ValkeyModuleCtx *ctx, ValkeyModuleEvent e, uint64_t sub, void *data)
+{
+    VALKEYMODULE_NOT_USED(e);
+    VALKEYMODULE_NOT_USED(sub);
+
+    ValkeyModuleAuthenticationInfo *ai = data;
+    LogStringEvent(ctx, "auth-attempt", ai->username);
+    if (ai->module_name) {
+        LogStringEvent(ctx, "auth-attempt-module", ai->module_name);
+    }
+    LogNumericEvent(ctx, "auth-attempt-success", ai->result == VALKEYMODULE_AUTH_RESULT_GRANTED);
+}
+
 static int cmdIsKeyRemoved(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int argc){
     if(argc != 2){
         return ValkeyModule_WrongArity(ctx);
@@ -453,6 +466,9 @@ int ValkeyModule_OnLoad(ValkeyModuleCtx *ctx, ValkeyModuleString **argv, int arg
     ValkeyModule_SubscribeToServerEvent(ctx,
         ValkeyModuleEvent_Key, keyInfoCallback);
 
+    ValkeyModule_SubscribeToServerEvent(ctx,
+        ValkeyModuleEvent_AuthenticationAttempt, authAttemptCallback);
+
     event_log = ValkeyModule_CreateDict(ctx);
     removed_event_log = ValkeyModule_CreateDict(ctx);
     removed_subevent_type = ValkeyModule_CreateDict(ctx);
diff --git a/tests/unit/moduleapi/hooks.tcl b/tests/unit/moduleapi/hooks.tcl
@@ -1,4 +1,5 @@
 set testmodule [file normalize tests/modules/hooks.so]
+set authmodule [file normalize tests/modules/auth.so]
 
 tags "modules" {
     start_server [list overrides [list loadmodule "$testmodule" appendonly yes]] {
@@ -226,6 +227,69 @@ tags "modules" {
             assert_equal [r hooks.event_last flush-end] -1
         }
 
+        test {Test success authentication attempt hooks} {
+            r acl setuser testuser on >testpass ~* +@all
+            r auth testuser testpass
+            assert_equal [r hooks.event_last auth-attempt] "testuser"
+            assert {[r hooks.event_count auth-attempt-module] < 1}
+            assert_equal [r hooks.event_last auth-attempt-success] "1"
+        }
+
+        test {Test failed authentication attempt hooks} {
+            r acl setuser testuser on >testpass ~* +@all
+            catch {r auth testuser wrongpass} e
+            assert_match {*WRONGPASS invalid username-password*} $e
+            assert_equal [r hooks.event_last auth-attempt] "testuser"
+            assert {[r hooks.event_count auth-attempt-module] < 1}
+            assert_equal [r hooks.event_last auth-attempt-success] "0"
+        }
+
+        test {Test success module authentication attempt hooks} {
+            r module load $authmodule
+            r testmoduleone.rm_register_auth_cb
+            r acl setuser foo on >testpass ~* +@all
+            r auth foo allow
+            assert_equal [r hooks.event_last auth-attempt] "foo"
+            assert_equal [r hooks.event_last auth-attempt-module] "testacl"
+            assert_equal [r hooks.event_last auth-attempt-success] "1"
+            r module unload testacl
+        }
+
+        test {Test failed module authentication attempt hooks} {
+            r module load $authmodule
+            r testmoduleone.rm_register_auth_cb
+            r acl setuser foo on ~* +@all
+            catch {r auth foo deny} e
+            assert_match {*Auth denied by Misc Module*} $e
+            assert_equal [r hooks.event_last auth-attempt] "foo"
+            assert_equal [r hooks.event_last auth-attempt-module] "testacl"
+            assert_equal [r hooks.event_last auth-attempt-success] "0"
+            r module unload testacl
+        }
+
+        test {Test success module blocking authentication attempt hooks} {
+            r module load $authmodule
+            r testmoduleone.rm_register_blocking_auth_cb
+            r acl setuser foo on ~* +@all
+            r auth foo block_allow
+            assert_equal [r hooks.event_last auth-attempt] "foo"
+            assert_equal [r hooks.event_last auth-attempt-module] "testacl"
+            assert_equal [r hooks.event_last auth-attempt-success] "1"
+            r module unload testacl
+        }
+
+        test {Test failed module blocking authentication attempt hooks} {
+            r module load $authmodule
+            r testmoduleone.rm_register_blocking_auth_cb
+            r acl setuser foo on ~* +@all
+            catch {r auth foo block_deny} e
+            assert_match {*Auth denied by Misc Module*} $e
+            assert_equal [r hooks.event_last auth-attempt] "foo"
+            assert_equal [r hooks.event_last auth-attempt-module] "testacl"
+            assert_equal [r hooks.event_last auth-attempt-success] "0"
+            r module unload testacl
+        }
+
         # replication related tests
         set master [srv 0 client]
         set master_host [srv 0 host]
