Domain-based access control
Permit only accounts from an approved email domain.
Auth.js · Function
signIn callback
The signIn callback decides whether an authentication attempt may continue. Return true to allow it, false to deny it, or a URL string to redirect the user.
How it works
The callback runs during the sign-in flow and decides whether access continues. Return true to proceed, false to stop and send the user to the error page, or a URL string to redirect the user there; asynchronous work such as checking a database or external API is supported.
Syntax
signIn: (params) => Awaitable<string | boolean>Parameters
| Name | Type | Description |
|---|---|---|
params | object | Object containing callback context; the documented example destructures profile from it. |
Returns
Awaitable<string | boolean>
Key points
- Use signIn as an authorization gate for the authentication attempt.
- A true result permits the normal sign-in process to continue.
- A string result changes the destination after the callback.
- The decision can use asynchronous data from a database or an external service.
- A domain rule can reject users whose email does not match the approved suffix.
Common mistakes
- Returning false and throwing an error have the same flow-stopping outcome: the user is sent to the error page.
- An uncaught callback error becomes an AccessDenied error, preserving the original message.
Example: Restrict sign-in by email domain
import NextAuth from "next-auth"
export const { handlers, auth } = NextAuth({
providers: [],
callbacks: {
async signIn({ profile }) {
return profile?.email?.endsWith("@example.com") ?? false
},
},
})Allows sign-in only when the profile email ends with the approved domain.
When to use it
External authorization check
Consult an external service before allowing authentication.
Conditional redirect
Send an authenticated user to a custom destination.
Interview questions
QWhat is the signIn callback's return contract?
The callback returns an Awaitable<string | boolean>. A boolean controls whether sign-in proceeds, while a string supplies a redirect destination.
Follow-up: What happens when it returns false? The sign-in flow stops and the user is redirected to the error page.
QHow can signIn restrict authentication?
Return true to continue, false to deny access, or a string to redirect the user to a specified URL. Because callbacks are asynchronous, the function may perform asynchronous checks before returning.
Follow-up: How could access be restricted without a local database? Await an external API or database check and return its authorization result.
QWhat does the callback receive?
It receives a params object, which can be destructured for values such as profile. The documented example checks the profile email domain and returns the resulting boolean.
Follow-up: What should an implementation do for providers without the expected profile field? Use optional access or provider-specific checks so the callback returns an explicit decision.
Related
callbacksjwt callbacksession callbackredirect callbackAccessDenied