Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
Guides
Refresh Token Rotation
💡

As of today, there is no built-in solution for automatic Refresh Token rotation. This guide will help you to achieve this in your application. Our goal is to add zero-config support for built-in providers eventually. Let us know if you would like to help.

What is refresh token rotation?

Refresh token rotation is the practice of updating an access_token on behalf of the user, without requiring interaction (ie.: re-authenticating). access_tokens are usually issued for a limited time. After they expire, the service verifying them will ignore the value, rendering the access_token useless. Instead of asking the user to sign in again to obtain a new access_token, many providers also issue a refresh_token during initial signin, that has a longer expiry date. Auth.js libraries can be configured to use this refresh_token to obtain a new access_token without requiring the user to sign in again.

Implementation

There is an inherent limitation of the following guides that comes from the fact, that - for security reasons - refresh_tokens are usually only usable once. Meaning that after a successful refresh, the refresh_token will be invalidated and cannot be used again. Therefore, in some cases, a race-condition might occur if multiple requests will try to refresh the token at the same time. The Auth.js team is aware of this and would like to provide a solution in the future. This might include some “lock” mechanism to prevent multiple requests from trying to refresh the token at the same time, but that comes with the drawback of potentially creating a bottleneck in the application. Another possible solution is background token refresh, to prevent the token from expiring during an authenticated request.

First, make sure that the provider you want to use supports refresh_token’s. Check out The OAuth 2.0 Authorization Framework spec for more details. Depending on the session strategy, the refresh_token can be persisted either in an encrypted JWT inside a cookie or in a database.

JWT strategy

💡

While using a cookie to store the refresh_token is simpler, it is less secure. To mitigate risks with the strategy: "jwt", Auth.js libraries store the refresh_token in an encrypted JWT, in an HttpOnly cookie. Still, you need to evaluate based on your requirements which strategy you choose.

Using the jwt and session callbacks, we can persist OAuth tokens and refresh them when they expire.

Below is a sample implementation of refreshing the access_token with Google. Please note that the OAuth 2.0 request to get the refresh_token will vary between different providers, but the rest of logic should remain similar.

./auth.ts
import NextAuth, { type User } from "next-auth"
import Google from "next-auth/providers/google"
 
export const { handlers, auth } = NextAuth({
  providers: [
    Google({
      // Google requires "offline" access_type to provide a `refresh_token`
      authorization: { params: { access_type: "offline", prompt: "consent" } },
    }),
  ],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        // First-time login, save the `access_token`, its expiry and the `refresh_token`
        return {
          ...token,
          access_token: account.access_token,
          expires_at: account.expires_at,
          refresh_token: account.refresh_token,
        }
      } else if (Date.now() < token.expires_at * 1000) {
        // Subsequent logins, but the `access_token` is still valid
        return token
      } else {
        // Subsequent logins, but the `access_token` has expired, try to refresh it
        if (!token.refresh_token) throw new TypeError("Missing refresh_token")
 
        try {
          // The `token_endpoint` can be found in the provider's documentation. Or if they support OIDC,
          // at their `/.well-known/openid-configuration` endpoint.
          // i.e. https://accounts.google.com/.well-known/openid-configuration
          const response = await fetch("https://oauth2.googleapis.com/token", {
            method: "POST",
            body: new URLSearchParams({
              client_id: process.env.AUTH_GOOGLE_ID!,
              client_secret: process.env.AUTH_GOOGLE_SECRET!,
              grant_type: "refresh_token",
              refresh_token: token.refresh_token!,
            }),
          })
 
          const tokensOrError = await response.json()
 
          if (!response.ok) throw tokensOrError
 
          const newTokens = tokensOrError as {
            access_token: string
            expires_in: number
            refresh_token?: string
          }
 
          token.access_token = newTokens.access_token
          token.expires_at = Math.floor(
            Date.now() / 1000 + newTokens.expires_in
          )
          // Some providers only issue refresh tokens once, so preserve if we did not get a new one
          if (newTokens.refresh_token)
            token.refresh_token = newTokens.refresh_token
          return token
        } catch (error) {
          console.error("Error refreshing access_token", error)
          // If we fail to refresh the token, return an error so we can handle it on the page
          token.error = "RefreshTokenError"
          return token
        }
      }
    },
  },
  session: ({ session, token }) => {
    session.error = token.error
    return session
  },
})
 
declare module "next-auth" {
  interface Session {
    error?: "RefreshTokenError"
  }
}
 
declare module "next-auth/jwt" {
  interface JWT {
    access_token: string
    expires_at: number
    refresh_token?: string
    error?: "RefreshTokenError"
  }
}

Database strategy

Using the database session strategy is similar, but instead we will save the access_token, expires_at and refresh_token on the account for the given provider.

./auth.ts
import NextAuth from "next-auth"
import Google from "next-auth/providers/google"
import { PrismaAdapter } from "@auth/prisma-adapter"
import { PrismaClient } from "@prisma/client"
 
const prisma = new PrismaClient()
 
export const { handlers, signIn, signOut, auth } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    Google({
      authorization: { params: { access_type: "offline", prompt: "consent" } },
    }),
  ],
  callbacks: {
    async session({ session, user }) {
      const [googleAccount] = await prisma.account.findMany({
        where: { userId: user.id, provider: "google" },
      })
      if (googleAccount.expires_at * 1000 < Date.now()) {
        // If the access token has expired, try to refresh it
        try {
          // https://accounts.google.com/.well-known/openid-configuration
          // We need the `token_endpoint`.
          const response = await fetch("https://oauth2.googleapis.com/token", {
            method: "POST",
            body: new URLSearchParams({
              client_id: process.env.AUTH_GOOGLE_ID!,
              client_secret: process.env.AUTH_GOOGLE_SECRET!,
              grant_type: "refresh_token",
              refresh_token: googleAccount.refresh_token,
            }),
          })
 
          const tokensOrError = await response.json()
 
          if (!response.ok) throw tokensOrError
 
          const newTokens = tokensOrError as {
            access_token: string
            expires_in: number
            refresh_token?: string
          }
 
          await prisma.account.update({
            data: {
              access_token: newTokens.access_token,
              expires_at: Math.floor(Date.now() / 1000 + newTokens.expires_in),
              refresh_token:
                newTokens.refresh_token ?? googleAccount.refresh_token,
            },
            where: {
              provider_providerAccountId: {
                provider: "google",
                providerAccountId: googleAccount.providerAccountId,
              },
            },
          })
        } catch (error) {
          console.error("Error refreshing access_token", error)
          // If we fail to refresh the token, return an error so we can handle it on the page
          session.error = "RefreshTokenError"
        }
      }
      return session
    },
  },
  session: ({ session, token }) => {
    session.error = token.error
    return session
  },
})
 
declare module "next-auth" {
  interface Session {
    error?: "RefreshTokenError"
  }
}

Error handling

If the token refresh was unsuccesful, we can force a re-authentication.

app/dashboard/page.tsx
import { useEffect } from "react"
import { auth, signIn } from "@/auth"
 
export default async function Page() {
  const session = await useSession()
  if (session?.error === "RefreshTokenError") {
    await signIn("google") // Force sign in to obtain a new set of access and refresh tokens
  }
}
Auth.js © Balázs Orbán and Team - 2024