adapters

Auth.js can be integrated with any data layer (database, ORM, or backend API, HTTP client) in order to automatically create users, handle account linking automatically, support passwordless login, and to store session information.

This module contains utility functions and types to create an Auth.js compatible adapter.

Auth.js supports 2 session strategies to persist the login state of a user. The default is to use a cookie + JWT based session store (strategy: "jwt"), but you can also use a database adapter to store the session in a database.

Before you continue, Auth.js has a list of official database adapters. If your database is listed there, you probably do not need to create your own. If you are using a data solution that cannot be integrated with an official adapter, this module will help you create a compatible adapter.

Note

Although @auth/core is framework/runtime agnostic, an adapter might rely on a client/ORM package, that is not yet compatible with your framework/runtime (e.g. it might rely on Node.js APIs). Related issues should be reported to the corresponding package maintainers.

Installation

npm

npm install @auth/core

yarn

yarn add @auth/core

pnpm

pnpm add @auth/core

Then, you can import this submodule from @auth/core/adapters.

Usage

Each adapter method and its function signature is documented in the Adapter interface.

my-adapter.ts

import { type Adapter } from "@auth/core/adapters"

// 1. Simplest form, a plain object.
export const MyAdapter: Adapter {
 // implement the adapter methods here
}

// or

// 2. A function that returns an object. Official adapters use this pattern.
export function MyAdapter(config: any): Adapter {
 // Instantiate a client/ORM here with the provided config, or pass it in as a parameter.
 // Usually, you might already have a client instance elsewhere in your application,
 // so you should only create a new instance if you need to or you don't have one.

 return {
   // implement the adapter methods
 }
}

Then, you can pass your adapter to Auth.js as the adapter option.

index.ts

import { MyAdapter } from "./my-adapter"

const response = await Auth(..., {
  adapter: MyAdapter, // 1.
  // or
  adapter: MyAdapter({ /* config */ }), // 2.
  ...
})

Note, you might be able to tweak an existing adapter to work with your data layer, instead of creating one from scratch.

my-adapter.ts

import { type Adapter } from "@auth/core/adapters"
import { PrismaAdapter } from "@next-auth/prisma-adapter"
import { PrismaClient } from "@prisma/client"

const prisma = new PrismaClient()

const adapter: Adapter = {
  ...PrismaAdapter(prisma),
  // Add your custom methods here
}

const request = new Request("https://example.com")
const response = await Auth(request, { adapter, ... })

Testing

There is a test suite available to ensure that your adapter is compatible with Auth.js.

Known issues

The following are missing built-in features in Auth.js but can be solved in user land. If you would like to help implement these features, please reach out.

Token rotation

Auth.js currently does not support access_token rotation out of the box. The necessary information (refresh_token, expiry, etc.) is being stored in the database, but the logic to rotate the token is not implemented in the core library. This guide should provide the necessary steps to do this in user land.

Federated logout

Auth.js currently does not support federated logout out of the box. This means that even if an active session is deleted from the database, the user will still be signed in to the identity provider, they will only be signed out of the application. Eg. if you use Google as an identity provider, and you delete the session from the database, the user will still be signed in to Google, but they will be signed out of your application.

If your users might be using the application from a publicly shared computer (eg: library), you might want to implement federated logout. This guide should provide the necessary steps.

Adapter

An adapter is an object with function properties (methods) that read and write data from a data source. Think of these methods as a way to normalize the data layer to common interfaces that Auth.js can understand.

This is what makes Auth.js very flexible and allows it to be used with any data layer.

The adapter methods are used to perform the following operations:

• Create/update/delete a user
• Link/unlink an account to/from a user
• Handle active sessions
• Support passwordless authentication across multiple devices

note

If any of the methods are not implemented, but are called by Auth.js, an error will be shown to the user and the operation will fail.

Methods

createSession()?

Creates a session for the user and returns it.

Optional createSession(session: object): Awaitable<AdapterSession>

Parameters

Parameter	Type
session	object
session.expires	Date
session.sessionToken	string
session.userId	string

Returns

Awaitable<AdapterSession>

deleteSession()?

Deletes a session from the database. It is preferred that this method also returns the session that is being deleted for logging purposes.

Optional deleteSession(sessionToken: string): Promise<void> | Awaitable<undefined | null | AdapterSession>

Parameters

Parameter	Type
sessionToken	string

Returns

Promise<void> | Awaitable<undefined | null | AdapterSession>

deleteUser()?

Todo

This method is currently not invoked yet.

Optional deleteUser(userId: string): Promise<void> | Awaitable<undefined | null | AdapterUser>

Parameters

Parameter	Type
userId	string

Returns

Promise<void> | Awaitable<undefined | null | AdapterUser>

getUserByAccount()?

Using the provider id and the id of the user for a specific account, get the user.

Optional getUserByAccount(providerAccountId: Pick<AdapterAccount, "provider" | "providerAccountId">): Awaitable<null | AdapterUser>

Parameters

Parameter	Type
providerAccountId	Pick<AdapterAccount, "provider" | "providerAccountId">

Returns

Awaitable<null | AdapterUser>

linkAccount()?

This method is invoked internally (but optionally can be used for manual linking). It creates an Account in the database.

Optional linkAccount(account: AdapterAccount): Promise<void> | Awaitable<undefined | null | AdapterAccount>

Parameters

Parameter	Type
account	AdapterAccount

Returns

Promise<void> | Awaitable<undefined | null | AdapterAccount>

unlinkAccount()?

Todo

This method is currently not invoked yet.

Optional unlinkAccount(providerAccountId: Pick<AdapterAccount, "provider" | "providerAccountId">): Promise<void> | Awaitable<undefined | AdapterAccount>

Parameters

Parameter	Type
providerAccountId	Pick<AdapterAccount, "provider" | "providerAccountId">

Returns

Promise<void> | Awaitable<undefined | AdapterAccount>

useVerificationToken()?

Return verification token from the database and delete it so it cannot be used again.

Optional useVerificationToken(params: object): Awaitable<null | VerificationToken>

Parameters

Parameter	Type
params	object
params.identifier	string
params.token	string

Returns

Awaitable<null | VerificationToken>

---

AdapterAccount

An account is a connection between a user and a provider.

There are two types of accounts:

• OAuth/OIDC accounts, which are created when a user signs in with an OAuth provider.
• Email accounts, which are created when a user signs in with an Email provider.

One user can have multiple accounts.

Properties

provider

provider: string

Provider's id for this account. Eg.: "google"

Inherited from

Account.provider

providerAccountId

providerAccountId: string

This value depends on the type of the provider being used to create the account.

• oauth/oidc: The OAuth account's id, returned from the profile() callback.
• email: The user's email address.
• credentials: id returned from the authorize() callback

Inherited from

Account.providerAccountId

expires_at?

expires_at: number

Calculated value based on OAuth2TokenEndpointResponse.expires_in.

It is the absolute timestamp (in seconds) when the OAuth2TokenEndpointResponse.access_token expires.

This value can be used for implementing token rotation together with OAuth2TokenEndpointResponse.refresh_token.

See

• https://authjs.dev/guides/basics/refresh-token-rotation#database-strategy
• https://www.rfc-editor.org/rfc/rfc6749#section-5.1

Inherited from

Account.expires_at

---

AdapterSession

A session holds information about a user's current signin state.

Properties

expires

expires: Date

The absolute date when the session expires.

If a session is accessed prior to its expiry date, it will be extended based on the maxAge option as defined in by SessionOptions.maxAge. It is never extended more than once in a period defined by SessionOptions.updateAge.

If a session is accessed past its expiry date, it will be removed from the database to clean up inactive sessions.

sessionToken

sessionToken: string

A randomly generated value that is used to look up the session in the database when using "database" AuthConfig.strategy option. This value is saved in a secure, HTTP-Only cookie on the client.

userId

userId: string

Connects the active session to a user in the database

---

AdapterUser

A user represents a person who can sign in to the application. If a user does not exist yet, it will be created when they sign in for the first time, using the information (profile data) returned by the identity provider. A corresponding account is also created and linked to the user.

Properties

email

email: string

The user's email address.

Overrides

User.email

emailVerified

emailVerified: null | Date

Whether the user has verified their email address via an Email provider. It is null if the user has not signed in with the Email provider yet, or the date of the first successful signin.

id

id: string

A unique identifier for the user.

Overrides

User.id

---

VerificationToken

A verification token is a temporary token that is used to sign in a user via their email address. It is created when a user signs in with an Email provider. When the user clicks the link in the email, the token and email is sent back to the server where it is hashed and compared to the value in the database. If the tokens and emails match, and the token hasn't expired yet, the user is signed in. The token is then deleted from the database.

Properties

expires

expires: Date

The absolute date when the token expires.

identifier

identifier: string

The user's email address.

token

token: string

A hashed token, using the AuthConfig.secret value.

---