Traditional credentials authentication
A username-and-password login backed by an existing application API.
Auth.js · Type Alias
CredentialsConfig
CredentialsConfig defines the options for Auth.js’s Credentials provider. It specifies sign-in inputs and custom authorization behavior, with authorize returning a User on success or null on failure.
How it works
CredentialsConfig describes the configuration accepted by Auth.js’s Credentials provider. It lets you define the credential inputs and an authorize callback that handles the submitted request and returns either a User for success or null for failure.
Syntax
type CredentialsConfig<CredentialsInputs extends Record<string, CredentialInput>> = CommonProviderOptions & { credentials: CredentialsInputs; authorize: (credentials: Partial<Record<keyof CredentialsInputs, unknown>>, request: Request) => Awaitable<null | User>; }Parameters
| Name | Type | Description |
|---|---|---|
config | Partial<CredentialsConfig<CredentialsInputs>> | Configuration options for the Credentials provider, including credential input definitions and authorization logic. |
credentials | CredentialsInputs | Definitions for the credential fields exposed by the provider and default sign-in form. |
credentials | Partial<Record<keyof CredentialsInputs, unknown>> | Submitted credential values. |
request | Request | The original authentication request. |
Returns
CredentialsConfig<CredentialsInputs> configures the Credentials provider; authorize returns Awaitable<null | User>.
Key points
- CredentialsConfig is the configuration object required when setting up the Credentials provider.
- CredentialsInputs both type-checks authorize input and controls the default sign-in form fields.
- The authorize callback accepts submitted credentials and a Request, and may return a User asynchronously or null.
- authorize is the extension point for implementing custom credential verification.
- Successful authentication requires authorize to return a User object.
- The callback receives the original HTTP request, which can be used when forwarding or inspecting the sign-in submission.
Example: Credentials provider configuration
import Credentials from "next-auth/providers/credentials"
Credentials({
credentials: {
username: { label: "Username" },
password: { label: "Password", type: "password" },
},
async authorize({ request }) {
const response = await fetch(request)
if (!response.ok) return null
return (await response.json()) ?? null
},
})This config defines the sign-in fields and forwards the request to an authentication service; a successful response must provide a User.
When to use it
Arbitrary credential forms
A login requiring several custom fields rather than OAuth.
Custom authentication mechanisms
Authentication through a domain-specific or hardware-backed credential flow.
Interview questions
QWhat is CredentialsConfig used for?
CredentialsConfig configures the Credentials provider. Its credentials property describes the form inputs, while authorize receives the submitted credentials and request and returns Awaitable<null | User>.
Follow-up: What indicates failed authentication? Returning null from authorize; a successful login must return a User object.
QWhat does the credentials property control?
The credentials map determines the available input keys and the fields rendered by the default sign-in page. Its keys are typed through CredentialsInputs, providing type safety inside authorize.
Follow-up: Why does the input definition affect authorize? The same keys determine the Partial<Record<keyof CredentialsInputs, unknown>> shape passed to the callback.
QHow does authorize determine whether sign-in succeeds?
authorize gets the submitted credentials and original Request, giving full control over custom authentication handling. It may perform asynchronous work because its return type is Awaitable.
Follow-up: What should an implementation do when an upstream authentication request fails? Return null rather than a User.
Related
CredentialsCredentialsInputsCredentialInputUserProvider