Allow or reject sign-in based on user or profile data
Access control
Auth.js · Pipe
callbacks
Auth.js callbacks are asynchronous hooks that control authentication actions, including sign-in decisions, JWT contents, redirects, and client-visible session data. Configure them inside the callbacks option.
How it works
Auth.js callbacks are asynchronous functions configured under callbacks. They run during authentication-related actions, letting you control sign-in decisions, token contents, redirects, and the session data exposed to the client.
Syntax
callbacks: {
jwt: (params) => Awaitable<null | JWT>;
redirect: (params) => Awaitable<string>;
session: (params) => Awaitable<Session | DefaultSession>;
signIn: (params) => Awaitable<string | boolean>;
}Parameters
| Name | Type | Description |
|---|---|---|
params | object | Callback-specific context such as token, user, session, profile, account, trigger, or URL, depending on the callback. |
Returns
Callback-dependent Awaitable values: jwt returns null or JWT; redirect returns a string; session returns Session or DefaultSession; signIn returns string or boolean.
Key points
- Configure callbacks as asynchronous functions that customize Auth.js behavior during authentication actions.
- Callbacks can enforce access rules even when the application does not use a database.
- The jwt callback stores its returned token data and makes it available to the session callback.
- The redirect callback runs when Auth.js redirects a user to a callback URL, including sign-in and sign-out.
- A true result from signIn permits the sign-in process to continue.
- A false result or thrown error rejects the sign-in flow and sends the user to the error page.
Common mistakes
- Values returned from the session callback are sent to the client, so do not place sensitive data there.
- Adding a property to the JWT does not automatically add it to the client-facing session; copy it explicitly in the session callback.
- The redirect callback does not allow arbitrary hosts by default.
Example: Expose a token value in the session
import NextAuth from "next-auth"
export const { handlers, auth } = NextAuth({
providers: [],
callbacks: {
async session({ session, token }) {
session.user.id = token.id
return session
},
},
})The session callback copies a value from the token into the session returned to the client.
When to use it
Add application data to a token and forward selected fields to the session
JWT sessions
Choose which session properties are exposed to the browser
Client session shaping
Customize permitted redirect destinations
Navigation control
Interview questions
QWhat are Auth.js callbacks?
Callbacks are asynchronous functions configured in Auth.js to control what happens during authentication actions. They can implement access controls and integrate with databases or APIs.
Follow-up: Which callback controls client-visible session data? The session callback does, and its return value is exposed to the client.
QWhen does the jwt callback run, and what is its role?
The jwt callback runs when a JWT is created at sign-in or updated when the client accesses a session. Values returned by it are saved in the JWT and can then be forwarded by the session callback.
Follow-up: How would you expose a token property? Return that property from the session callback as part of the session object.
QHow does signIn control authentication?
The signIn callback determines whether sign-in continues. Returning true continues, returning false or throwing stops the flow and redirects to the error page, while returning a string redirects to that URL.
Follow-up: How can access be restricted by email domain? Inspect the profile in signIn and return whether its email ends with the permitted domain.
Related
jwt callbacksession callbacksignIn callbackredirect callbackauthorized callbackJWTAuthConfig