Audit logging
Record successful authentication activity for security review.
Auth.js · Enum
signIn event
events.signIn is an asynchronous Auth.js event handler for work triggered by a sign-in. It is intended for side effects such as audit logging, not for controlling whether authentication succeeds.
How it works
The events.signIn handler runs asynchronously after a sign-in-related event and receives a message whose contents depend on the authentication flow and session strategy. Use it for side effects such as audit logging; it does not decide whether access is allowed.
Syntax
signIn: (message) => Awaitable<void>Returns
Awaitable<void>
Key points
- Use
events.signInfor side effects such as recording successful sign-ins or creating audit entries. - Auth.js lets the configuration include a dedicated handler for the sign-in event alongside other event handlers.
- The message commonly provides a user object, JWT contents, or other event-specific information.
- Typical applications include debugging authentication behavior and maintaining an authentication audit trail.
Common mistakes
- Do not use this event to allow or deny authentication or to redirect the user; it is for asynchronous side effects.
- Do not assume the message has the same shape for OAuth, email, JWT-session, and database-session flows.
Example: Audit a sign-in event
import NextAuth from "next-auth";
export const { handlers, auth } = NextAuth({
providers: [],
events: {
async signIn(message) {
console.log("User signed in", message.user?.id);
},
},
});Register an asynchronous handler to record each completed sign-in event.
When to use it
Debugging auth flows
Inspect authentication payloads while integrating providers or session strategies.
External side effects
Send a notification or update an external system after sign-in.
Interview questions
QWhat is the purpose of the signIn event?
events.signIn is an asynchronous event handler configured under events. It is useful for audit logging and does not return a response.
Follow-up: How would you decide whether a user may sign in? Use the callbacks.signIn callback, whose return value can continue, stop, or redirect the flow.
QWhat can the signIn event message contain?
The handler receives a message object. Its exact contents depend on the authentication flow and session strategy, but it commonly includes a user and/or JWT information.
Follow-up: What should production code do with that variability? Treat optional fields defensively and log only the data required for the audit record.
QHow do you configure a sign-in event handler?
Configure it in the Auth.js options as events: { signIn: async (message) => { ... } }. The handler can perform asynchronous work such as writing an audit entry.
Follow-up: What is the corresponding authorization mechanism? Configure callbacks.signIn, not events.signIn, when access control is required.
Related
eventscallbacks.signIncreateUserlinkAccountsessionsignOutupdateUser