Responding to a new authentication

Sometimes we need to do a little work when someone finishes signing in: record the event, create a local account record, or refresh contact details. The onAuthenticated callback gives us that point in the flow.

Adding a callback

Supply the callback when constructing Authenticator in the shared setup:

use Authwave\Authenticator;
use Authwave\AuthUser;

$auth = new Authenticator(
	clientKey: $clientKey,
	currentUriPath: $_SERVER["REQUEST_URI"],
	onAuthenticated: function(AuthUser $user):void {
		error_log("Authentication completed for user " . $user->id);
	},
);

Here $clientKey and the session have already been prepared as shown in the Quick start guide. The callback receives the same user data that getAuthUser() makes available after authentication.

When it runs

The callback runs during construction, after the response has been decrypted and the new user data has been stored in the session, but before the redirect that removes AUTHWAVE_RESPONSE_DATA.

It does not run when an ordinary request restores an existing user from the session. Put work needed on every authenticated request after construction, guarded by isLoggedIn().

Handling application failures

The client marks the callback as invoked before calling it. If it throws, the exception propagates and the tidy-up redirect is skipped. Reprocessing the same response with the stored callback marker will not invoke the callback again.

This is an at-most-once callback for that authentication exchange, rather than a retry mechanism. If the work must survive a temporary database or service failure, make the operation safe to repeat and arrange retries in the application. Do not rely on refreshing the return page to retry it.

A new login() exchange creates fresh session data. Separate login exchanges can therefore invoke the callback again.

---

Next, see Provider configuration and return URIs for deployment and redirect settings.