Skip to main content

Module: 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.

An adapter is a unified interface of methods that Auth.js is calling internally. They all have the same signature and return the same data structure, so Auth.js does not need to concern itself with the data layer's implementation details.

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 install @auth/core

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

Usage​

Adapter methods often use a client/ORM package to interact with the data layer. Therefore, official adapters are usually functions that return an Adapter interface, to which you pass a client/ORM instance and other configuration options. It is not a requirement, but it is a common pattern.

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 discussion should provide the necessary steps.

Interfaces​