DynamoDB-backed authentication
Persist Auth.js users, accounts, sessions, and verification data in Amazon DynamoDB.
Auth.js · Const
DynamoDBAdapter
DynamoDBAdapter creates an Auth.js database adapter backed by DynamoDB. It requires an AWS SDK v3 DynamoDBDocument client and optionally accepts configuration for table and key names.
How it works
DynamoDBAdapter accepts an already-created AWS SDK v3 DynamoDBDocument client and optional adapter settings, then returns an Auth.js Adapter that persists authentication data in DynamoDB. Without options, it uses the adapter's expected table and key layout; options can customize names and keys.
Syntax
function DynamoDBAdapter(client, options?): AdapterParameters
| Name | Type | Description |
|---|---|---|
client | DynamoDBDocument | AWS SDK v3 DynamoDB document client used for adapter operations. |
options | DynamoDBAdapterOptions | Optional table-name and key/index configuration. |
Returns
Adapter
Key points
- DynamoDBAdapter is the official DynamoDB integration for Auth.js and NextAuth.js.
- Call it with a required client and optional options object; the result implements Auth.js Adapter.
- The default table layout uses pk as the partition key and sk as the sort key.
- The default design also requires a GSI named GSI1.
Common mistakes
- Pass a DynamoDBDocument client from AWS SDK v3 rather than a low-level DynamoDB client.
- The default table is named next-auth; provide tableName when using a different table.
- A custom table must match the expected partition and sort-key structure unless the corresponding options are configured.
Example: Configure the DynamoDB adapter
import NextAuth from "next-auth";
import { DynamoDB } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
import { DynamoDBAdapter } from "@auth/dynamodb-adapter";
const client = DynamoDBDocument.from(new DynamoDB({
region: process.env.AUTH_DYNAMODB_REGION,
credentials: {
accessKeyId: process.env.AUTH_DYNAMODB_ID!,
secretAccessKey: process.env.AUTH_DYNAMODB_SECRET!,
},
}));
export const { handlers, auth } = NextAuth({
providers: [],
adapter: DynamoDBAdapter(client),
});Creates an AWS SDK v3 DynamoDBDocument client and supplies it to DynamoDBAdapter in Auth.js configuration.
When to use it
Custom table configuration
Use an existing DynamoDB table with customized names or keys.
Official adapter integration
Configure Auth.js with the official AWS DynamoDB adapter package.
Interview questions
QWhat does DynamoDBAdapter return?
DynamoDBAdapter is a factory function. It receives a DynamoDBDocument client plus optional DynamoDBAdapterOptions and returns an Auth.js Adapter.
Follow-up: How would you connect it to Auth.js? Pass the returned value as the adapter property in the NextAuth configuration.
QWhat client must be supplied?
The client parameter is typed as DynamoDBDocument. The documentation specifically requires the modular AWS SDK v3 document client.
Follow-up: Why use the document client? It provides the document-oriented interface expected by this adapter instead of requiring low-level attribute-value handling.
QWhat DynamoDB schema assumptions matter?
The adapter uses next-auth as its default table name and expects pk/sk keys plus the GSI1 index with GSI1PK and GSI1SK by default. Options can customize these table and key settings.
Follow-up: What should be checked before deployment? Verify that the deployed table and global secondary index match the adapter configuration.
Related
DynamoDBAdapterOptionsDynamoDBDocumentAdapter@auth/dynamodb-adaptergenerateUpdateExpression