Merge branch 'main' into frederikprijck-patch-1

Author: frederikprijck

.version

@@ -1 +1 @@
-v4.1.0
+v4.4.0

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Change Log
 
+## [v4.4.0](https://github.com/auth0/nextjs-auth0/tree/v4.4.0) (2025-04-01)
+[Full Changelog](https://github.com/auth0/nextjs-auth0/compare/v4.3.0...v4.4.0)
+
+**Added**
+- Add note about access-token endpoint to README [\#2020](https://github.com/auth0/nextjs-auth0/pull/2020) ([frederikprijck](https://github.com/frederikprijck))
+- Add support for Connection Access Token [\#2010](https://github.com/auth0/nextjs-auth0/pull/2010) ([frederikprijck](https://github.com/frederikprijck))
+
+**Fixed**
+- fix: Delete legacy cookie once v4 cookie is set [\#2019](https://github.com/auth0/nextjs-auth0/pull/2019) ([frederikprijck](https://github.com/frederikprijck))
+- fix: Ensure to delete cookies when switching from single to chunks and vica versa [\#2013](https://github.com/auth0/nextjs-auth0/pull/2013) ([frederikprijck](https://github.com/frederikprijck))
+- fix: Clean up cookie chunks when cookie size shrinks [\#2014](https://github.com/auth0/nextjs-auth0/pull/2014) ([frederikprijck](https://github.com/frederikprijck))
+- fix: use NEXT_PUBLIC_PROFILE_ROUTE in Auth0Provider [\#2021](https://github.com/auth0/nextjs-auth0/pull/2021) ([tusharpandey13](https://github.com/tusharpandey13))
+- fix: Ensure to pass-through enableAccessTokenEndpoint [\#2015](https://github.com/auth0/nextjs-auth0/pull/2015) ([frederikprijck](https://github.com/frederikprijck))
+- fix: Remove obsolete warning about cookie-size [\#2012](https://github.com/auth0/nextjs-auth0/pull/2012) ([frederikprijck](https://github.com/frederikprijck))
+
+## [v4.3.0](https://github.com/auth0/nextjs-auth0/tree/v4.3.0) (2025-03-28)
+[Full Changelog](https://github.com/auth0/nextjs-auth0/compare/v4.2.1...v4.3.0)
+
+**Added**
+- Access Token Exposure Control [\#1979](https://github.com/auth0/nextjs-auth0/pull/1979) ([tusharpandey13](https://github.com/tusharpandey13))
+- Cookie chunking support [\#1975](https://github.com/auth0/nextjs-auth0/pull/1975) ([tusharpandey13](https://github.com/tusharpandey13))
+- Add idToken to TokenSet in SessionData [\#1978](https://github.com/auth0/nextjs-auth0/pull/1978) ([tusharpandey13](https://github.com/tusharpandey13))
+
+## [v4.2.1](https://github.com/auth0/nextjs-auth0/tree/v4.2.1) (2025-03-24)
+[Full Changelog](https://github.com/auth0/nextjs-auth0/compare/v4.2.0...v4.2.1)
+
+**Changed**
+- Bump next in SDK as well as examples [\#1992](https://github.com/auth0/nextjs-auth0/pull/1992) ([frederikprijck](https://github.com/frederikprijck))
+
+## [v4.2.0](https://github.com/auth0/nextjs-auth0/tree/v4.2.0) (2025-03-23)
+[Full Changelog](https://github.com/auth0/nextjs-auth0/compare/v4.1.0...v4.2.0)
+
+**Security**
+- Enforce nextjs peerDependency to 14.2.25 and 15.2.3 [\#1988](https://github.com/auth0/nextjs-auth0/pull/1988) ([frederikprijck](https://github.com/frederikprijck))
+
+The above security fix was done to help prevent customers being vulnerable to [Authorization Bypass in Next.js Middleware](https://github.com/advisories/GHSA-f82v-jwr5-mffw).
+
 ## [v4.1.0](https://github.com/auth0/nextjs-auth0/tree/v4.1.0) (2025-03-13)
 [Full Changelog](https://github.com/auth0/nextjs-auth0/compare/v4.0.3...v4.1.0)
 

EXAMPLES.md

@@ -32,6 +32,14 @@
   - [Custom routes](#custom-routes)
 - [Testing helpers](#testing-helpers)
   - [`generateSessionCookie`](#generatesessioncookie)
+- [Programmatically starting interactive login](#programmatically-starting-interactive-login)
+  - [Passing authorization parameters](#passing-authorization-parameters-1)
+  - [The `returnTo` parameter](#the-returnto-parameter-1)
+    - [Redirecting the user after authentication](#redirecting-the-user-after-authentication-1)
+- [Getting access tokens for connections](#getting-access-tokens-for-connections)
+  - [On the server (App Router)](#on-the-server-app-router-3)
+  - [On the server (Pages Router)](#on-the-server-pages-router-3)
+  - [Middleware](#middleware-3)
 
 ## Passing authorization parameters
 
@@ -60,14 +68,18 @@ The `returnTo` parameter can be appended to the login to specify where you would
 
 For example: `/auth/login?returnTo=/dashboard` would redirect the user to the `/dashboard` route after they have authenticated.
 
+> [!NOTE]  
+> The URL specified as `returnTo` parameters must be registered in your client's **Allowed Callback URLs**.
+
+
 ### Redirecting the user after logging out
 
 The `returnTo` parameter can be appended to the logout to specify where you would like to redirect the user after they have logged out.
 
 For example: `/auth/login?returnTo=https://example.com/some-page` would redirect the user to the `https://example.com/some-page` URL after they have logged out.
 
 > [!NOTE]  
-> The URLs specified as `returnTo` parameters must be registered in your client's **Allowed Logout URLs**.
+> The URL specified as `returnTo` parameters must be registered in your client's **Allowed Logout URLs**.
 
 ## Accessing the authenticated user
 
@@ -185,6 +197,15 @@ export async function middleware(request: NextRequest) {
 > [!IMPORTANT]  
 > The `request` object must be passed as a parameter to the `getSession(request)` method when called from a middleware to ensure that any updates to the session can be read within the same request.
 
+## Accessing the idToken
+`idToken` can be accessed from the session in the following way:
+
+```js
+const session = await auth0.getSession();
+const idToken = session.tokenSet.idToken;
+```
+
+
 ## Updating the session
 
 The `updateSession` method could be used to update the session of the currently authenticated user in the App Router, Pages Router, and middleware. If the user does not have a session, an error will be thrown.
@@ -753,32 +774,200 @@ const sessionCookieValue = await generateSessionCookie(
 )
 ```
 
+## Programmatically starting interactive login
 
-## Programmatic Pushed Authentication Requests (PAR)
-
-The method `startInteractiveLogin` can be called with authorizationParams to initiate an interactive login flow.  
-The code collects authorization parameters on the server side rather than constructing them directly in the browser.
+Additionally to the ability to initialize the interactive login process by redirecting the user to the built-in `auth/login` endpoint,
+the `startInteractiveLogin` method can also be called programmatically.
 
 ```typescript
-// app/api/auth/login/route.ts
 import { auth0 } from "./lib/auth0";
 import { NextRequest } from "next/server";
 
 export const GET = async (req: NextRequest) => {
-  // Extract custom parameters from request URL if needed
-  const searchParams = Object.fromEntries(req.nextUrl.searchParams.entries());
+  return auth0.startInteractiveLogin();
+};
+```
+
+### Passing authorization parameters
+
+There are 2 ways to customize the authorization parameters that will be passed to the `/authorize` endpoint when calling `startInteractiveLogin` programmatically. The first option is through static configuration when instantiating the client, like so:
+
+```ts
+export const auth0 = new Auth0Client({
+  authorizationParameters: {
+    scope: "openid profile email",
+    audience: "urn:custom:api",
+  },
+});
+```
+
+The second option is by configuring `authorizationParams` when calling `startInteractiveLogin`:
 
+```ts
+import { auth0 } from "./lib/auth0";
+import { NextRequest } from "next/server";
+
+export const GET = async (req: NextRequest) => {
   // Call startInteractiveLogin with optional parameters
   return auth0.startInteractiveLogin({
-    // a custom returnTo URL can be specified
-    returnTo: "/dashboard",
     authorizationParameters: {
-      prompt: searchParams.prompt,
-      login_hint: searchParams.login_hint,
-      // Add any custom auth parameters if required
-      audience: "custom-audience"
+      scope: "openid profile email",
+      audience: "urn:custom:api",
     }
   });
 };
+```
+
+## The `returnTo` parameter
+
+### Redirecting the user after authentication
+
+When calling `startInteractiveLogin`, the `returnTo` parameter can be configured to specify where you would like to redirect the user to after they have completed their authentication and have returned to your application.
+
+```ts
+import { auth0 } from "./lib/auth0";
+import { NextRequest } from "next/server";
+
+export const GET = async (req: NextRequest) => {
+  return auth0.startInteractiveLogin({
+    returnTo: '/dashboard',
+  });
+};
+```
+
+> [!NOTE]  
+> The URLs specified as `returnTo` parameters must be registered in your client's **Allowed Callback URLs**.
+
+
+## Getting access tokens for connections
+You can retrieve an access token for a connection using the `getAccessTokenForConnection()` method, which accepts an object with the following properties:
+- `connection`: The federated connection for which an access token should be retrieved.
+- `login_hint`: The optional login_hint parameter to pass to the `/authorize` endpoint.
+
+### On the server (App Router)
+
+On the server, the `getAccessTokenForConnection()` helper can be used in Server Routes, Server Actions and Server Components to get an access token for a connection.
+
+> [!IMPORTANT]  
+> Server Components cannot set cookies. Calling `getAccessTokenForConnection()` in a Server Component will cause the access token to be refreshed, if it is expired, and the updated token set will not to be persisted.
+>
+> It is recommended to call `getAccessTokenForConnection(req, res)` in the middleware if you need to refresh the token in a Server Component as this will ensure the token is refreshed and correctly persisted.
+
+For example:
+
+```ts
+import { NextResponse } from "next/server"
+
+import { auth0 } from "@/lib/auth0"
+
+export async function GET() {
+  try {
+    const token = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' })
+    // call external API with token...
+  } catch (err) {
+    // err will be an instance of AccessTokenError if an access token could not be obtained
+  }
+
+  return NextResponse.json({
+    message: "Success!",
+  })
+}
+```
+
+Upon further calls for the same provider, the cached value will be used until it expires.
+
+### On the server (Pages Router)
+
+On the server, the `getAccessTokenForConnection({}, req, res)` helper can be used in `getServerSideProps` and API routes to get an access token for a connection, like so:
+
+```ts
+import type { NextApiRequest, NextApiResponse } from "next"
+
+import { auth0 } from "@/lib/auth0"
 
-```
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse<{ message: string }>
+) {
+  try {
+    const token = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' }, req, res)
+  } catch (err) {
+    // err will be an instance of AccessTokenError if an access token could not be obtained
+  }
+
+  res.status(200).json({ message: "Success!" })
+}
+```
+
+### Middleware
+
+In middleware, the `getAccessTokenForConnection({}, req, res)` helper can be used to get an access token for a connection, like so:
+
+```tsx
+import { NextRequest, NextResponse } from "next/server"
+
+import { auth0 } from "@/lib/auth0"
+
+export async function middleware(request: NextRequest) {
+  const authRes = await auth0.middleware(request)
+
+  if (request.nextUrl.pathname.startsWith("/auth")) {
+    return authRes
+  }
+
+  const session = await auth0.getSession(request)
+
+  if (!session) {
+    // user is not authenticated, redirect to login page
+    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
+  }
+
+  const accessToken = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' }, request, authRes)
+
+  // the headers from the auth middleware should always be returned
+  return authRes
+}
+```
+
+> [!IMPORTANT]  
+> The `request` and `response` objects must be passed as a parameters to the `getAccessTokenForConnection({}, request, response)` method when called from a middleware to ensure that the refreshed access token can be accessed within the same request.
+
+If you are using the Pages Router and are calling the `getAccessTokenForConnection` method in both the middleware and an API Route or `getServerSideProps`, it's recommended to propagate the headers from the middleware, as shown below. This will ensure that calling `getAccessTokenForConnection` in the API Route or `getServerSideProps` will not result in the access token being refreshed again.
+
+```ts
+import { NextRequest, NextResponse } from "next/server"
+
+import { auth0 } from "@/lib/auth0"
+
+export async function middleware(request: NextRequest) {
+  const authRes = await auth0.middleware(request)
+
+  if (request.nextUrl.pathname.startsWith("/auth")) {
+    return authRes
+  }
+
+  const session = await auth0.getSession(request)
+
+  if (!session) {
+    // user is not authenticated, redirect to login page
+    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
+  }
+
+  const accessToken = await auth0.getAccessTokenForConnection({ connection: 'google-oauth2' }, request, authRes)
+
+  // create a new response with the updated request headers
+  const resWithCombinedHeaders = NextResponse.next({
+    request: {
+      headers: request.headers,
+    },
+  })
+
+  // set the response headers (set-cookie) from the auth response
+  authRes.headers.forEach((value, key) => {
+    resWithCombinedHeaders.headers.set(key, value)
+  })
+
+  // the headers from the auth middleware should always be returned
+  return resWithCombinedHeaders
+}
+```

README.md

@@ -151,21 +151,24 @@ You can customize the client by using the options below:
 
 The SDK mounts 6 routes:
 
-1. `/auth/login`: the login route that the user will be redirected to to start a initiate an authentication transaction
-2. `/auth/logout`: the logout route that must be addedto your Auth0 application's Allowed Logout URLs
-3. `/auth/callback`: the callback route that must be addedto your Auth0 application's Allowed Callback URLs
+1. `/auth/login`: the login route that the user will be redirected to to initiate an authentication transaction
+2. `/auth/logout`: the logout route that must be added to your Auth0 application's Allowed Logout URLs
+3. `/auth/callback`: the callback route that must be added to your Auth0 application's Allowed Callback URLs
 4. `/auth/profile`: the route to check the user's session and return their attributes
 5. `/auth/access-token`: the route to check the user's session and return an access token (which will be automatically refreshed if a refresh token is available)
 6. `/auth/backchannel-logout`: the route that will receive a `logout_token` when a configured Back-Channel Logout initiator occurs
 
+> [!IMPORTANT]  
+> The `/auth/access-token` route is enabled by default, but is only neccessary when the access token is needed in the client. If this isn't something you need, you can disable this endpoint by setting `enableAccessTokenEndpoint` to `false`.
+
 ## Feedback
 
 ### Contributing
 
 We appreciate feedback and contribution to this repo! Before you get started, please read the following:
 
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
-- [Auth0's code of conduct guidelines](https://github.com/auth0/express-openid-connect/blob/master/CODE-OF-CONDUCT.md)
+- [Auth0's code of conduct guidelines](https://github.com/auth0/nextjs-auth0/blob/main/CODE-OF-CONDUCT.md)
 - [This repo's contribution guide](./CONTRIBUTING.md)
 
 ### Raise an issue
@@ -189,5 +192,5 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
   Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
 </p>
 <p align="center">
-  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/express-openid-connect/blob/master/LICENSE"> LICENSE</a> file for more info.
+  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/nextjs-auth0/blob/main/LICENSE"> LICENSE</a> file for more info.
 </p>

V4_MIGRATION_GUIDE.md

@@ -235,9 +235,6 @@ If you'd like to customize the `user` object to include additional custom claims
 ## Additional changes
 
 - By default, v4 is edge-compatible and as such there is no longer a `@auth0/nextjs-auth0/edge` export.
-- Cookie chunking has been removed
-  - If the cookie size exceeds the browser limit of 4096 bytes, a warning will be logged
-  - To store large session data, please use a [custom data store](https://github.com/auth0/nextjs-auth0/tree/main?tab=readme-ov-file#database-sessions) with a SessionStore implementation
 - All cookies set by the SDK default to `SameSite=Lax`
 - `touchSession` method was removed. The middleware enables rolling sessions by default and can be configured via the [session configuration](https://github.com/auth0/nextjs-auth0/tree/main?tab=readme-ov-file#session-configuration).
 - `getAccessToken` can now be called in React Server Components.