Responding to a new authentication

Use the authentication callback to record a sign-in or create a local account record.

Adding a callback

def on_authenticated(user: AuthUser) -> None:
    logger.info('Authentication completed for %s', user.id)

# Pass on_authenticated=on_authenticated to the client or framework adapter.

When it runs

The callback runs synchronously after the new user and callback marker are stored, before the cleanup redirect. Ordinary session restoration does not invoke it. Put per-request work after construction, guarded by the login state.

Handling application failures

A thrown exception propagates and skips the cleanup redirect. The runtime adapter still saves the callback marker, so reprocessing the same response does not invoke it again.

The callback runs at most once per exchange under sequential session processing. Make external operations idempotent and arrange retries through application infrastructure. Queue asynchronous work separately. A fresh login creates new exchange state and can invoke the callback again.

---

Next, see Provider configuration and return URIs.