Existing authentication backend
An application already has a username/password or enterprise login service and needs Auth.js to connect to it.
Auth.js · Function
Credentials
Auth.js’s Credentials provider lets you implement custom sign-in with arbitrary fields and your own validation logic. It is intended for existing authentication systems, does not persist these users in the database, and requires JWT sessions.
How it works
The Credentials provider delegates authentication to your own authorize callback. It receives the submitted fields, and a returned user object accepts the login while null rejects it; users authenticated this way are not stored by the database adapter.
Syntax
Credentials({ credentials, authorize })Parameters
| Name | Type | Description |
|---|---|---|
credentials | Record<string, CredentialInput> | Map of credential field names to input definitions used by the sign-in form. |
authorize | (credentials, request) => Awaitable<null | User> | Callback receiving submitted credentials and the request; returns a user or null. |
Returns
The authorize callback returns an Awaitable containing either null or a User; the configured provider participates in Auth.js sign-in.
Key points
- Use it for custom inputs, including username/password, domain credentials, two-factor authentication, or hardware-device authentication.
- The provider is suited to delegating verification to an external or pre-existing authentication service.
- Define each login input in credentials; those definitions control the default form.
- Put application-specific verification in authorize.
- authorize must resolve to a user object for success or null for rejection.
- Submitted form values are forwarded to your authentication service or validation code.
Common mistakes
- Credentials authentication does not persist users in the database.
- Use JWT sessions because database-backed sessions are not supported for this provider.
- Returning null from authorize rejects the sign-in.
Example: Credentials provider
import NextAuth from "next-auth"
import Credentials from "next-auth/providers/credentials"
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [
Credentials({
credentials: {
username: { label: "Username" },
password: { label: "Password", type: "password" },
},
async authorize(credentials) {
const user = await verifyAgainstExistingSystem(credentials)
return user ?? null
},
}),
],
})Configure the provider with the sign-in fields and return a user object when external validation succeeds; return null to reject the login.
When to use it
Custom credential formats
A login flow uses nonstandard inputs such as a one-time code, second factor, or hardware-device credential.
Development authentication
A development-only test login is needed without configuring an OAuth provider.
Interview questions
QWhat is the Credentials provider used for?
The provider is intended for arbitrary inputs such as passwords, two-factor data, or hardware-device credentials. Its authorize callback controls validation and returns either a user or null.
Follow-up: What persistence constraint applies? Users authenticated through this provider are not persisted in the database, so JWT sessions must be enabled.
QHow do credentials and authorize work together?
The credentials object describes the fields shown on the default sign-in page. authorize receives the submitted values and performs the custom authentication logic.
Follow-up: What happens when validation fails? Return null, which causes the login to fail.
QWhat session and database limitations apply?
Credentials authentication is designed for an existing authentication system, so Auth.js does not persist these users in the database. Sessions therefore require JSON Web Tokens.
Follow-up: Why is this different from many OAuth providers? OAuth users can be persisted through an adapter, whereas this provider delegates identity verification to your custom logic.
Related
CredentialsConfigauthorizeCredentialInputUserJWT sessionssignIn