4.0.2 (2021-12-02)

Bug Fixes

• remove nextauth from authorization params (#3332) (4dcdb62)

This post should cover the most important changes. https://balazsorban.com/blog/next-auth-v4

4.0.0-beta.7 (2021-11-15)

Bug Fixes

• providers: set 42 default scope (#3189) (38cefdd)
• allow configuring http timeout (#3188) (b871b47)
• bump openid-client (#3063) (da991de), closes #3052
• correctly transpile all client-side submodules (#3100) (1597369)
• normalize URL before parsing (#3077) (b66afcc)
• respect host in getServerSession (#3179) (e9ac11b)
• use error query param if set (#3141) (0d7d8da)
• oauth: allow 10 sec clock tolerance (#3071) (4181988)

Features

• allow relative redirects (#3140) (6502b63)
• Clerk to README supporters (533ed94)
• introduce chunking when session cookie becomes too big (#3101) (f9e0ef8)
• make missing secret an error (#3143) (76bf524)
• rename session strategy (#3144) (ba39efb)

BREAKING CHANGES

• It is now required to set a secret in production.
• The session.jwt: boolean option has been renamed to session.strategy: "jwt" | "database". The goal is to make the user's options more intuitive:

1. No adapter, strategy: "jwt": This is the default. The session is saved in a cookie and never persisted anywhere.
2. With Adapter, strategy: "database": If an Adapter is defined, this will be the implicit setting. No user config is needed.
3. With Adapter, strategy: "jwt": The user can explicitly instruct next-auth to use JWT even if a database is available. This can result in faster lookups in compromise of lowered security. Read more about: https://next-auth.js.org/faq#json-web-tokens

Example:

session: {
-  jwt: true,
+ strategy: "jwt",
}

4.0.0-beta.6 (2021-10-29)

Bug Fixes

• providers: add default id_token_signed_response_alg to LINE (#3059) (5725931)
• uuid import (#3056) (c8b7e2e)

Features

• react: preserve history on client-side navigation (#2980) (1d9b7b8)

4.0.0-beta.5 (2021-10-27)

Bug Fixes

• providers: Refactor Line Provider (#2917) (129d161)
• providers: resize default AzureAD profile picture (#2910) (58a98b6)
• conditionally render theme logo on builtin pages (#2916) (19e326e)

Features

• update jose and openid-client (#3039) (72408ab)

BREAKING CHANGES

• The jwt option has been simplified and the NextAuth.js issued JWT is now encrypted by default.

If you want to override the defaults, you can still use the encode and decode functions. These are advanced options and they should only be used if you know what you are doing.

The default secret generation comment has been removed in this PR, which will be added back in a separate one. Remember, that is only for developer convenience, it is highly recommended to always create your own secret for production.

4.0.0-beta.4 (2021-10-03)

Bug Fixes

• correctly set authorization url for OAuth1 (#2884) (dfff2e6)

4.0.0-beta.3 (2021-10-03)

Bug Fixes

• providers: refactor LinkedIn provider (#2821) (1d52600)
• providers: refactor Okta provider (#2856) (f635035)
• providers: remove extra brace from jwks_uri (#2813) (04fc3fd)
• providers: convert to TS, add picture (#2851) (9e1eab0)
• providers: make string endpoint handlers overrideable (#2842) (b052d4c)
• providers: refactor Azure AD provider to support v4 (#2818) (424bd04)
• signin: Set default input type to text to fix CSS (#2881) (0707ba6)
• login logo height (a177bbb)
• use default export map syntax for ESM/CJS (#2830) (ffa2b1b)
• ts: add defaults to OAuthConfig generics (a2c4046)
• respect id from user options in signinUrl and callbackUrl id (#2698) (819e97e)

Features

• providers: expose openid-client options client and jwks (#2717) (50e6a64)
• providers: refactor Azure B2C provider (#2862) (72d4c5b)
• providers: refactor Cognito provider (#2829) (5066726)
• providers: refactor Slack provider (#2848) (f0551b0)
• signin: Support passing any argument to credentials input (#2876) (c5bd99d)
• built-in page theme updates (#2788) (cabcdc9), closes #67b246

4.0.0-beta.2 (2021-09-07)

Bug Fixes

• ts: forward credentials fields to authorize (#2683) (3b23cfe)
• ts: hint built-in provider types in signIn (#2655) (17bea4a)
• ts: make options on useSession optional (419ffe7), closes #2674
• ts: make OAuth profile overrideable (#2682) (0989acc)

4.0.0-beta.1 (2021-09-05)

Bug Fixes

• avoid infinite loop in error handlers (#2647) (245567b)
• build: use optional-require dependency (#1736) (9fa93e3)
• callback: respect callbackUrl in Email Provider (#2574) (a9f699f)
• provider: convert github profile id from int to string (#2108) (ea9b6e3)
• provider: make userinfo.params optional (#2517) (65040dc)
• provider: remove double CSS from email template (2c43fbd)
• react: don't use localStorage on server side (#2166) (abaa5ae)
• react: initialize session without loading state (#2180) (86ff89e)
• react: publish react scripts with npm build (#2192) (d10bd9b)
• ts: add AzureAD to OAuthProviderType (ed34534)
• ts: allow void return type on delete operations (78d8f28)
• ts: fix internal react type import (#2450) (92b9d22)
• use upgraded require optional (#1743) (a6f5f4c)

Features

• build: modernize how we bundle next-auth (#1682) (cb4342f)
• client: remove staleTime (#2613) (08349c3)
• provider: add Keycloak provider (#2485) (eb8ba69)
• provider: use more restrictive default scope for GitHub (#2579) (e15bf9b)
• simplify Adapter API (#2361) (8914f88)
• provider: require to import every provider individually (#2518) (55132e5)
• improve OAuth provider configuration (#2411) (7c65bda), closes #1846 #1605 #1607 /github.com/panva/node-openid-client/blob/51dc47d9ac619b71cd1c983b0be750a12bbae008/types/index.d.ts#L108-L143
• adapter: remove adapters from core (#1919) (960bc1e)
• core: use named params in callbacks (#2173) (2833b66)
• events: include profile on signIn events (#2356) (3312e53)
• events: use named params for all event callbacks (#2342) (111d5fc)
• logger: simplify logger API (#2344) (acc9393), closes #2342 #1602
• rename protection to checks (#2255) (6911dd9)
• provider: refactor Azure AD, B2C providers (#1591) (5ac1db7)
• provider: remove state property (111e7aa)
• react: make session requireable in useSession (#2236) (a2e5afa)
• bump dependencies (#2254) (6c1a0ec)
• react: create client tailored to React (#1473) (ca0ed1e), closes #1461 #1084 #1462
• encourage returning strings instead of throwing (a113ef6)
• use IE11 as client code bundle target (#1402) (c20b7f2)

BREAKING CHANGES

• client: staleTime (previously clientMaxAge) has been removed. Check out refetchInterval instead. It should cover most of the cases. If not, we can look into adding this back later on.
• provider: By default, the GitHub Provider scope won't ask for full write access to user profiles. If you need that, you will now have to add the user scope to your configuration.
• prisma-legacy is now gone. Use @next-auth/prisma-adapter. Any features from the old adapter will be migrated over to the new one eventually. This is done so we can require the same default set of options from all the built-in providers, rather than allowing ambiguity on what an official adapter has to support.

The TypeORM adapter will probably be the only one migrated as-is, but in the future, we would like to break it down to lighter-weight adapters that only support single databases.

Adapters no longer have to return a getAdapter() method, they can return the actual adapter methods instead. All the values previously being provided through the arguments of getAdapter will now be available in a more digestible format directly in the concerning methods. This behavior was created so that connections could be handled more efficiently. Our review has shown that currently, the TypeORM adapter is the only one that does not handle connections out-of-the-box, so we are going to look into how we can create a wrapper/util function to make it work in the new version. For all other adapters, this will be a huge gain, as with this new API, methods are actually overrideable without creating a whole new custom adapter! 🥳

Example:

function MySlightlyCustomAdapter(...args) {
  const adapter = AdapterFromSomeoneElse(...args)
  adapter.someMethodIWantToModify = (...args) => {
    // Much better implementation goes here.
  }
  return adapter
}

The following method names are changing:

- getSession
+ getSessionAndUser

This method now requires that you return both the user and the session as {user, session}. If any of these could not be retrieved, you will have to return null instead. (In other words, this must be a transaction.) This requires one less database call, improving the user session retrieval. Any expiry logic included in the Adapter before is now done in the core as well.

- createVerificationRequest
+ createVerificationToken

Better describes the functionality. This method no longer needs to call provider.sendVerificationRequest, we are moving this into the core. This responsibility shouldn't have fallen to the adapter in the first place.

createVerificationToken will now receive a VerificationToken object, which looks like this:

interface VerificationToken {
  identifier: string
  expires: Date
  token: string
}

The token provided is already hashed, so nothing has to be done, simply write it to your database. (Here we lift up the responsibility from the adapter to hash tokens)

- getVerificationRequest
+ useVerificationToken

Better describes the functionality. It now also has the responsibility to delete the used-up token from the database. Most ORMs should support retrieving the value while deleting it at the same time, so it will reduce the number of database calls.

- deleteVerificationRequest

This method is gone. See useVerificationToken.

Most of the method signatures have been changed, have a look at the TypeScript interface to get a better picture.

• provider: Providers now have to be imported one-by-one:

Example:

- import Provider from "next-auth/providers"
- Providers.Auth0({...})
+ import Auth0Provider from "next-auth/providers/auth0"
+ Auth0Provider({...})

• events: Two event signatures changed to use named params, signOut and updateUser:

// [...nextauth].js
...
events: {
- signOut(tokenOrSession),
+ signOut({ token, session }), // token if using JWT, session if DB persisted sessions.
- updateUser(user)
+ updateUser({ user })
}

• logger: The main change is that instead of an unknown number of parameters, the log events have at most two, where the second parameter is usually an object. In the case of the error event, it can also be an Error instance (that is serializable by JSON.stringify). If it is an object, an Error instance will be available on metadata.error, and message will default to metadata.error.message. This is done so that an error event always provides some kind of a stack to see where the error happened

// [...nextauth.js]
import log from "some-logger-service"
...
logger: {
- error(code, ...message) {},
+ error(code, metadata) {},
- warn(code, ...message) {},
+ warn(code) {}
- debug(code, ...message) {}
+ debug(code, metadata) {}
}

• The state option on OAuth providers is now deprecated. Use checks: ["state"] instead.
  protections is renamed to checks, here is an example:

- protection: ["pkce"]
+ checks: ["pkece"]

Furthermore, string values are not supported anymore. This is to be able to handle fewer cases internally.

- checks: "state"
+ checks: ["state"]

• react: The useSession hook now returns an object. Here is how to accommodate for this change:

- const [ session, loading ] = useSession()
+ const { data: session, status } = useSession()
+ const loading = status === "loading"

With the new status option, you can test states much more clearly.

• core: The callbacks method signatures are changing the following way:

- signIn(user, account, profileOrEmailOrCredentials)
+ signIn({ user, account, profile, email, credentials })

- redirect(url, baseUrl)
+ redirect({ url, baseUrl })

- session(session, tokenOrUser)
+ session({ session, token, user })

- jwt(token, user, account, OAuthProfile, isNewUser)
+ jwt({ token, user, account, profile, isNewUser })

NOTE: You only need to define the params that you actually need (no more need for _ params.)

This way, if you only need token and account in the jwt callback, you can write:

jwt({ token, account }) {
  if(account) {
    token.accessToken = account.access_token
  }
  return token
}

• The lowest supported Node version is 12. (We still support IE11 in browsers, until that is not dropped by Next.js itself)

react:

1. next-auth/client is renamed to next-auth/react.

2. In the past, we exposed most of the functions with different names for convenience. To simplify our source code, the new React specific client code exports only the following functions, listed with the necessary changes:

• setOptions: Not exposed anymore, use SessionProvider props
• options: Not exposed anymore, use SessionProvider props
• session: Rename to getSession
• providers: Rename to getProviders
• csrfToken: Rename to getCsrfToken
• signin: Rename to signIn
• signout: Rename to signOut
• Provider: Rename to SessionProvider

3. Provider changes.

• Provider is renamed to SessionProvider
• The options prop is now flattened as the props of SessionProvider.
• keepAlive has been renamed to refetchInterval.
  An example of the changes:

- <Provider options={{clientMaxAge: 0, keepAlive: 0}}>{children}</Provider>
+ <SessionProvider refetchInterval={0}>{children}</SessionProvider> 

4. It is now required to wrap the part of your application that uses useSession into a SessionProvider.

Usually, the best place for this is in your pages/_app.jsx file:

import { SessionProvider } from "next-auth/react"

export default function App({
  Component,
  pageProps: { session, ...pageProps }
}) {
  return (
    // `session` comes from `getServerSideProps` or `getInitialProps`.
    // Avoids flickering/session loading on first load.
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  )
}

• provider: If you currently use AzureADB2C, you will need to update it to to AzureAD There should be no other changes needed.
• adapter: From now on, you will have to import your own adapter

Check out https://github.com/nextauthjs/adapters

The migration is super easy and has HUGE advantages for those not using TypeORM.

// [...nextauth].js
+ import TypeORMAdapter from "@next-auth/typeorm-legacy-adapter"
import NextAuth from "next-auth"

...
export default NextAuth({
-  database: "yourconnectionstring",
+ adapter: TypeORMAdapter("yourconnectionstring")
})

Co-authored-by: Lluis Agusti [email protected]
Co-authored-by: Giovanni Carnel [email protected]

• build: typeorm, and nodemailer are no longer dependencies added by default.
  If you need any of them, you will have to install them yourself in your project directory.
  TypeOrm is the default adapter, so if you only provide an adapter configuration or a database, you will need typeorm. You could also check out @next-auth/typeorm-adapter. In case you are using the Email provider, you will have to install nodemailer (or you can use the choice of your library in the sendVerificationRequest callback to send out the e-mail.)
• provider: adding state: true is already redundant
  as protection: "state is the default value. state: false
  can be substituted with protection: "state"
• We have supported throwing strings
  for redirections, while we were showing a waring.
  From now on, it is not possible. The user MUST return a string,
  rather than throw it.

4.0.0-next.26 (2021-09-02)

Bug Fixes

• avoid infinite loop in error handlers (#2647) (245567b)

4.0.0-next.25 (2021-08-29)

Features

• client: remove staleTime (#2613) (08349c3)

BREAKING CHANGES

• client: staleTime (previously clientMaxAge) has been removed. Check out refetchInterval instead. It should cover most of the cases. If not, we can look into adding this back later on.

4.0.0-next.24 (2021-08-23)

Bug Fixes

• callback: respect callbackUrl in Email Provider (#2574) (a9f699f)
• provider: remove double CSS from email template (2c43fbd)

Features

• provider: add Keycloak provider (#2485) (eb8ba69)
• provider: use more restrictive default scope for GitHub (#2579) (e15bf9b)

BREAKING CHANGES

• provider: By default, the GitHub Provider scope won't ask for full write access to user profiles. If you need that, you will now have to add the user scope to your configuration.

3.29.0 (2021-08-23)

Bug Fixes

• deps: update built-in adapter dependencies (#2589) (ead7152)

Features

• provider: return image for Yandex by default (#2563) (90a6a00)

4.0.0-next.23 (2021-08-16)

Bug Fixes

• ts: allow void return type on delete operations (78d8f28)

4.0.0-next.22 (2021-08-15)

Bug Fixes

• provider: make userinfo.params optional (#2517) (65040dc)

Features

• simplify Adapter API (#2361) (8914f88)
• provider: require to import every provider individually (#2518) (55132e5)

BREAKING CHANGES

• prisma-legacy is now gone. Use @next-auth/prisma-adapter. Any features from the old adapter will be migrated over to the new one eventually. This is done so we can require the same default set of options from all the built-in providers, rather than allowing ambiguity on what an official adapter has to support.

The TypeORM adapter will probably be the only one migrated as-is, but in the future, we would like to break it down to lighter-weight adapters that only support single databases.

Adapters no longer have to return a getAdapter() method, they can return the actual adapter methods instead. All the values previously being provided through the arguments of getAdapter will now be available in a more digestible format directly in the concerning methods. This behavior was created so that connections could be handled more efficiently. Our review has shown that currently, the TypeORM adapter is the only one that does not handle connections out-of-the-box, so we are going to look into how we can create a wrapper/util function to make it work in the new version. For all other adapters, this will be a huge gain, as with this new API, methods are actually overrideable without creating a whole new custom adapter! 🥳

Example:

function MySlightlyCustomAdapter(...args) {
  const adapter = AdapterFromSomeoneElse(...args)
  adapter.someMethodIWantToModify = (...args) => {
    // Much better implementation goes here.
  }
  return adapter
}

The following method names are changing:

- getSession
+ getSessionAndUser

This method now requires that you return both the user and the session as {user, session}. If any of these could not be retrieved, you will have to return null instead. (In other words, this must be a transaction.) This requires one less database call, improving the user session retrieval. Any expiry logic included in the Adapter before is now done in the core as well.

- createVerificationRequest
+ createVerificationToken

Better describes the functionality. This method no longer needs to call provider.sendVerificationRequest, we are moving this into the core. This responsibility shouldn't have fallen to the adapter in the first place.

createVerificationToken will now receive a VerificationToken object, which looks like this:

interface VerificationToken {
  identifier: string
  expires: Date
  token: string
}

The token provided is already hashed, so nothing has to be done, simply write it to your database. (Here we lift up the responsibility from the adapter to hash tokens)

- getVerificationRequest
+ useVerificationToken

Better describes the functionality. It now also has the responsibility to delete the used-up token from the database. Most ORMs should support retrieving the value while deleting it at the same time, so it will reduce the number of database calls.

- deleteVerificationRequest

This method is gone. See useVerificationToken.

Most of the method signatures have been changed, have a look at the TypeScript interface to get a better picture.

• provider: Providers now have to be imported one-by-one:

Example:

- import Provider from "next-auth/providers"
- Providers.Auth0({...})
+ import Auth0Provider from "next-auth/providers/auth0"
+ Auth0Provider({...})

3.28.0 (2021-08-12)

Bug Fixes

• ts: allow scope as string array type (#2511) (66d16f8)

Features

• providers: add Freshbooks (#2322) (35ce332)
• providers: add OneLogin (#2345) (2155c93)

4.0.0-next.21 (2021-08-12)

Bug Fixes

• ts: fix internal react type import (#2450) (92b9d22)

4.0.0-next.20 (2021-08-04)

Features

• improve OAuth provider configuration (#2411) (7c65bda), closes #1846 #1605 #1607 /github.com/panva/node-openid-client/blob/51dc47d9ac619b71cd1c983b0be750a12bbae008/types/index.d.ts#L108-L143
• events: include profile on signIn events (#2356) (3312e53)
• events: use named params for all event callbacks (#2342) (111d5fc)

BREAKING CHANGES

• events: Two event signatures changed to use named params, signOut and updateUser:

// [...nextauth].js
...
events: {
- signOut(tokenOrSession),
+ signOut({ token, session }), // token if using JWT, session if DB persisted sessions.
- updateUser(user)
+ updateUser({ user })
}

• providers: Basecamp provider is removed. See the explanation here

ALL OAuth providers' profile callback is expected to only return these fields by default from now on: id, name, email, and image at most. Any of these missing values should be set to null.

The following new options are available:

1. authorization (replaces authorizationUrl, authorizationParams, scope)
2. token replaces (accessTokenUrl, headers, params)
3. userinfo (replaces profileUrl)

These three options map nicely to the OAuth spec's three endpoints for

1. initiating the login flow
2. retrieve OAuth tokens
3. retrieve user information

They all take the form of EndpointHandler:

type EndpointRequest<C, R> = (
  context: C & {
    /** `openid-client` Client */
    client: Client
    /** Provider is passed for convenience, ans also contains the `callbackUrl`. */
    provider: OAuthConfig & {
      signinUrl: string
      callbackUrl: string
    }
  }
) => Awaitable<R>

/** Gives granular control of the request to the given endpoint */
type AdvancedEndpointHandler<P extends UrlParams, C, R> = {
  /** Endpoint URL. Can contain parameters. Optionally, you can use `params`*/
  url?: string
  /** These will be prepended to the `url` */
  params?: P
  /**
   * Control the corresponding OAuth endpoint request completely.
   * Useful if your provider relies on some custom behavior
   * or it diverges from the OAuth spec.
   *
   * - warning **This is an advanced option.**
   * You should **try to avoid using advanced options** unless you are very comfortable using them.
   */
  request?: EndpointRequest<C, R>
}

/** Either an URL (containing all the parameters) or an object with more granular control. */
type EndpointHandler<P extends UrlParams, C = any, R = any> =
  | string
  | AdvancedEndpointHandler<P, C, R>

In case of authorization, the EndpointHandler can define the params as AuthorizationParameters

Note: authorization does not implement request yet. We will have to see if there is demand for it.

From now on, instead of using the ... spread operator when adding a new built-in provider, the user is expected to add options as a property at the end of the default config. This way, we can deep merge the user config with the default one. This is needed to let the user do something like this:

MyProvider({
  clientId: "",
  clientSecret: "",
  authorization: { params: {scope: ""} }
})

So even if the default config defines anything in authorization, only the user-defined parts will be overridden.

4.0.0-next.19 (2021-07-11)

Features

• logger: simplify logger API (#2344) (acc9393), closes #2342 #1602
• rename protection to checks (#2255) (6911dd9)

BREAKING CHANGES

• logger: The main change is that instead of an unknown number of parameters, the log events have at most two, where the second parameter is usually an object. In the case of the error event, it can also be an Error instance (that is serializable by JSON.stringify). If it is an object, an Error instance will be available on metadata.error, and message will default to metadata.error.message. This is done so that an error event always provides some kind of a stack to see where the error happened

// [...nextauth.js]
import log from "some-logger-service"
...
logger: {
- error(code, ...message) {},
+ error(code, metadata) {},
- warn(code, ...message) {},
+ warn(code) {}
- debug(code, ...message) {}
+ debug(code, metadata) {}
}

• The state option on OAuth providers is now deprecated. Use checks: ["state"] instead.
  protections is renamed to checks, here is an example:

- protection: ["pkce"]
+ checks: ["pkece"]

Furthermore, string values are not supported anymore. This is to be able to handle fewer cases internally.

- checks: "state"
+ checks: ["state"]

3.27.3 (2021-07-08)

Bug Fixes

• oauth: correctly remove code_verifier cookie when used (#2325) (f546e55)