Migrating from NextAuth.js v4 to Auth.js v5

NextAuth.js version 5 is a major rewrite of the next-auth package, which brings breaking updates that affect various integrations, including Logto. This guide will walk you through the process of migrating your Logto integration from NextAuth.js v4 to Auth.js v5.

We've recently update our NextAuth quick starts guide. Check it out!

Understanding the Changes#

Auth.js v5#

NextAuth.js v5 introduces several breaking changes, the main change that affect the way you integrate Logto with your application is the change on "OIDC/OAuth Providers". In the official documentation, it says "Auth.js now builds on @auth/core with stricter OAuth/OIDC spec-compliance, which might break some existing OAuth providers", for Logto users, this means you need to update the provider configuration.

For more information on the changes, you can refer to the official migration guide.

Logto provider configuration#

The provider configuration for Logto has been updated:

• The type has been changed from oauth to oidc.
• The wellKnown endpoint is removed, and you need to provide the issuer field instead.
• No need to specify the id_token signing algorithm, it supports ES384 now and it will be automatically detected.

Step-by-step migration guide#

Update the provider configuration in your pages/api/auth/[...nextauth].js file with the new configuration template:

Step 1: Change the provider type#

Change the provider type from oauth to oidc.

Step 2: Add the issuer field#

Add the issuer field to the provider configuration. You can get the issuer value from the Logto Application Details page, in the field "Issuer endpoint". It should look like https://xxxx.logto.app/oidc if you are using the Logto cloud service.

And then you can remove the wellKnown field.

Step 3: Remove the id_token_signed_response_alg signing algorithm#

You no longer need to specify the id_token_signed_response_alg signing algorithm in the provider configuration. It supports ES384 now and it will be automatically detected.

Update the project#

After updating the provider configuration, you need to update the next-auth package to v5, follow the official migration guide to update the package and make sure your application works as expected. Make sure you also reference NextAuth quick starts guide.