Add debug log when HMAC incorrect

changelog.d/18474.misc

@@ -0,0 +1 @@
+Add debug logging for HMAC digest verification failures when using the admin API to register users.

docker/conf/log.config

@@ -64,6 +64,10 @@ loggers:
         # beware: increasing this to DEBUG will make synapse log sensitive
         # information such as access tokens.
         level: INFO
+    synapse.rest.admin.users.registration_debug:
+        # beware: increasing this to DEBUG will make synapse log sensitive
+        # information such as passwords and `registration_shared_secret`.
+        level: INFO
     {% endif %}
 
     {% if SYNAPSE_LOG_TESTING %}

docs/usage/configuration/logging_sample_config.md

@@ -14,6 +14,9 @@ It should be named `<SERVERNAME>.log.config` by default.
 Hint: If you're looking for a guide on what each of the fields in the "Processed request" log lines mean,
 see [Request log format](../administration/request_log.md).
 
+Warn: Logging at the `DEBUG` level is very verbose and will include sensitive
+information such as access tokens, passwords, and secrets.
+
 ```yaml
 {{#include ../../sample_log_config.yaml}}
 ```

synapse/rest/admin/users.py

@@ -59,6 +59,14 @@
 
 logger = logging.getLogger(__name__)
 
+user_registration_debug_logger = logging.getLogger(
+    "synapse.rest.admin.users.registration_debug"
+)
+"""
+A logger for debugging the user registration process. This is separate from the main
+logger as it logs sensitive information such as passwords and `registration_shared_secret`.
+"""
+
 
 class UsersRestServletV2(RestServlet):
     PATTERNS = admin_patterns("/users$", "v2")
@@ -633,6 +641,13 @@ async def on_POST(self, request: SynapseRequest) -> Tuple[int, JsonDict]:
         want_mac = want_mac_builder.hexdigest()
 
         if not hmac.compare_digest(want_mac.encode("ascii"), got_mac.encode("ascii")):
+            user_registration_debug_logger.debug(
+                "UserRegisterServlet: Incorrect HMAC digest: actual=%s, expected=%s, registration_shared_secret=%s, body=%s",
+                got_mac,
+                want_mac,
+                self.hs.config.registration.registration_shared_secret,
+                body,
+            )
             raise SynapseError(HTTPStatus.FORBIDDEN, "HMAC incorrect")
 
         should_issue_refresh_token = body.get("refresh_token", False)