From 1814759e3871798dab7ea91e3280cab3fa792b39 Mon Sep 17 00:00:00 2001 From: Tushar Pandey Date: Wed, 11 Jun 2025 16:53:13 +0530 Subject: [PATCH 1/2] feat: add force refresh capabilities to client-side getAccessToken - Add GetAccessTokenOptions type with refresh parameter to client-side getAccessToken - Update server-side handleAccessToken to support refresh query parameter - Add comprehensive unit tests for force refresh functionality - Add E2E tests with force refresh buttons for both app and pages router - Update EXAMPLES.md with comprehensive client and server-side force refresh examples - Maintain backward compatibility with existing getAccessToken usage - Add proper TypeScript overloads and JSDoc documentation --- EXAMPLES.md | 63 ++++++++++++-- e2e/app-router.spec.ts | 24 +++++- e2e/pages-router.spec.ts | 24 +++++- e2e/test-app/app/app-router/client/page.tsx | 12 ++- .../pages/pages-router/client/index.tsx | 13 ++- src/client/helpers/get-access-token.ts | 48 ++++++++++- src/client/index.ts | 5 +- src/server/auth-client.test.ts | 82 +++++++++++++++++++ src/server/auth-client.ts | 12 ++- 9 files changed, 264 insertions(+), 19 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index 02280454..89cae5b3 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -386,9 +386,20 @@ export default function Component() { } } + async function fetchDataWithForceRefresh() { + try { + // Force a refresh of the access token + const token = await getAccessToken({ refresh: true }) + // call external API with refreshed token... + } catch (err) { + // err will be an instance of AccessTokenError if an access token could not be obtained + } + } + return (
+
) } @@ -525,7 +536,45 @@ export async function middleware(request: NextRequest) { In some scenarios, you might need to explicitly force the refresh of an access token, even if it hasn't expired yet. This can be useful if, for example, the user's permissions or scopes have changed and you need to ensure the application has the latest token reflecting these changes. -The `getAccessToken` method provides an option to force this refresh. +The force refresh capability is available across **all environments**: client-side (browser), App Router server-side, and Pages Router server-side. + +**Client-side (Browser):** + +When calling `getAccessToken()` from the browser, you can pass an options object to force a refresh: + +```tsx +"use client" + +import { getAccessToken } from "@auth0/nextjs-auth0" + +export default function Component() { + async function fetchData() { + try { + const token = await getAccessToken() + // call external API with token... + } catch (err) { + // err will be an instance of AccessTokenError if an access token could not be obtained + } + } + + async function fetchDataWithForceRefresh() { + try { + // Force a refresh of the access token + const token = await getAccessToken({ refresh: true }) + // call external API with refreshed token... + } catch (err) { + // err will be an instance of AccessTokenError if an access token could not be obtained + } + } + + return ( +
+ + +
+ ) +} +``` **App Router (Server Components, Route Handlers, Server Actions):** @@ -533,12 +582,12 @@ When calling `getAccessToken` without request and response objects, you can pass ```typescript // app/api/my-api/route.ts -import { getAccessToken } from '@auth0/nextjs-auth0'; +import { auth0 } from '@/lib/auth0'; export async function GET() { try { // Force a refresh of the access token - const { token, expiresAt } = await getAccessToken({ refresh: true }); + const { token, expiresAt } = await auth0.getAccessToken({ refresh: true }); // Use the refreshed token // ... @@ -555,16 +604,16 @@ When calling `getAccessToken` with request and response objects (from `getServer ```typescript // pages/api/my-pages-api.ts -import { getAccessToken, withApiAuthRequired } from '@auth0/nextjs-auth0'; +import { auth0 } from '@/lib/auth0'; import type { NextApiRequest, NextApiResponse } from 'next'; -export default withApiAuthRequired(async function handler( +export default async function handler( req: NextApiRequest, res: NextApiResponse ) { try { // Force a refresh of the access token - const { token, expiresAt } = await getAccessToken(req, res, { + const { token, expiresAt } = await auth0.getAccessToken(req, res, { refresh: true }); @@ -574,7 +623,7 @@ export default withApiAuthRequired(async function handler( console.error('Error getting access token:', error); res.status(error.status || 500).json({ error: error.message }); } -}); +} ``` By setting `{ refresh: true }`, you instruct the SDK to bypass the standard expiration check and request a new access token from the identity provider using the refresh token (if available and valid). The new token set (including the potentially updated access token, refresh token, and expiration time) will be saved back into the session automatically. diff --git a/e2e/app-router.spec.ts b/e2e/app-router.spec.ts index a4ea4303..6fee66b7 100644 --- a/e2e/app-router.spec.ts +++ b/e2e/app-router.spec.ts @@ -56,13 +56,33 @@ test("getAccessToken()", async ({ page }) => { await page.fill('input[id="password"]', process.env.TEST_USER_PASSWORD!); await page.getByText("Continue", { exact: true }).click(); - // fetch a token + // request a token const requestPromise = page.waitForRequest("/auth/access-token"); - await page.getByText("Get token").click(); + await page.getByText("Get access token").click(); + const request = await requestPromise; + const tokenRequest = await (await request?.response())?.json(); + expect(tokenRequest).toHaveProperty("token"); + expect(tokenRequest).toHaveProperty("expires_at"); +}); + +test("getAccessToken() with force refresh", async ({ page }) => { + await page.goto("/auth/login?returnTo=/app-router/client"); + + // fill out Auth0 form + await page.fill('input[id="username"]', "test@example.com"); + await page.fill('input[id="password"]', process.env.TEST_USER_PASSWORD!); + await page.getByText("Continue", { exact: true }).click(); + + // force refresh a token + const requestPromise = page.waitForRequest("/auth/access-token?refresh=true"); + await page.getByText("Force refresh token").click(); const request = await requestPromise; const tokenRequest = await (await request.response())?.json(); expect(tokenRequest).toHaveProperty("token"); expect(tokenRequest).toHaveProperty("expires_at"); + + // Verify that the request URL contains the refresh parameter + expect(request.url()).toContain("refresh=true"); }); test("protected server route", async ({ page, context }) => { diff --git a/e2e/pages-router.spec.ts b/e2e/pages-router.spec.ts index d85d5a9a..2874fa76 100644 --- a/e2e/pages-router.spec.ts +++ b/e2e/pages-router.spec.ts @@ -56,13 +56,33 @@ test("getAccessToken()", async ({ page }) => { await page.fill('input[id="password"]', process.env.TEST_USER_PASSWORD!); await page.getByText("Continue", { exact: true }).click(); - // fetch a token + // request a token const requestPromise = page.waitForRequest("/auth/access-token"); - await page.getByText("Get token").click(); + await page.getByText("Get access token").click(); + const request = await requestPromise; + const tokenRequest = await (await request?.response())?.json(); + expect(tokenRequest).toHaveProperty("token"); + expect(tokenRequest).toHaveProperty("expires_at"); +}); + +test("getAccessToken() with force refresh", async ({ page }) => { + await page.goto("/auth/login?returnTo=/pages-router/client"); + + // fill out Auth0 form + await page.fill('input[id="username"]', "test@example.com"); + await page.fill('input[id="password"]', process.env.TEST_USER_PASSWORD!); + await page.getByText("Continue", { exact: true }).click(); + + // force refresh a token + const requestPromise = page.waitForRequest("/auth/access-token?refresh=true"); + await page.getByText("Force refresh token").click(); const request = await requestPromise; const tokenRequest = await (await request.response())?.json(); expect(tokenRequest).toHaveProperty("token"); expect(tokenRequest).toHaveProperty("expires_at"); + + // Verify that the request URL contains the refresh parameter + expect(request.url()).toContain("refresh=true"); }); test("protected API route", async ({ page, request, context }) => { diff --git a/e2e/test-app/app/app-router/client/page.tsx b/e2e/test-app/app/app-router/client/page.tsx index 5b7a8e73..64237a87 100644 --- a/e2e/test-app/app/app-router/client/page.tsx +++ b/e2e/test-app/app/app-router/client/page.tsx @@ -21,6 +21,11 @@ export default function Profile() { ) } + const handleForceRefresh = async () => { + // TypeScript workaround: cast to any to use the overloaded signature + await (getAccessToken as any)({ refresh: true }) + } + return (

Welcome, {user?.email}!

@@ -29,7 +34,12 @@ export default function Profile() { await getAccessToken() }} > - Get token + Get access token + +
) diff --git a/e2e/test-app/pages/pages-router/client/index.tsx b/e2e/test-app/pages/pages-router/client/index.tsx index 86aa94b9..c83e71c2 100644 --- a/e2e/test-app/pages/pages-router/client/index.tsx +++ b/e2e/test-app/pages/pages-router/client/index.tsx @@ -21,6 +21,12 @@ export default function Profile() { ) } + const handleForceRefresh = async () => { + // TypeScript workaround: cast to any to use the overloaded signature + const token = await (getAccessToken as any)({ refresh: true }) + setToken(token) + } + return (

Welcome, {user?.email}!

@@ -35,7 +41,12 @@ export default function Profile() { setToken(token) }} > - Get token + Get access token + +
) diff --git a/src/client/helpers/get-access-token.ts b/src/client/helpers/get-access-token.ts index 3e152c70..4e2f7a03 100644 --- a/src/client/helpers/get-access-token.ts +++ b/src/client/helpers/get-access-token.ts @@ -6,10 +6,50 @@ type AccessTokenResponse = { expires_at?: number; }; -export async function getAccessToken(): Promise { - const tokenRes = await fetch( - process.env.NEXT_PUBLIC_ACCESS_TOKEN_ROUTE || "/auth/access-token" - ); +export type GetAccessTokenOptions = { + /** + * Force a refresh of the access token. + */ + refresh?: boolean; +}; + +/** + * Retrieves an access token from the `/auth/access-token` endpoint. + * + * @returns The access token string. + * @throws {AccessTokenError} If there's an error retrieving the access token. + */ +export async function getAccessToken(): Promise; + +/** + * Retrieves an access token from the `/auth/access-token` endpoint. + * + * @param options Configuration for getting the access token. + * @returns The access token string. + * @throws {AccessTokenError} If there's an error retrieving the access token. + */ +export async function getAccessToken( + options: GetAccessTokenOptions +): Promise; + +/** + * Retrieves an access token from the `/auth/access-token` endpoint. + * + * @param options Optional configuration for getting the access token. + * @returns The access token string. + * @throws {AccessTokenError} If there's an error retrieving the access token. + */ +export async function getAccessToken( + options?: GetAccessTokenOptions +): Promise { + const searchParams = new URLSearchParams(); + if (options?.refresh) { + searchParams.set("refresh", "true"); + } + + const url = `${process.env.NEXT_PUBLIC_ACCESS_TOKEN_ROUTE || "/auth/access-token"}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`; + + const tokenRes = await fetch(url); if (!tokenRes.ok) { // try to parse it as JSON and throw the error from the API diff --git a/src/client/index.ts b/src/client/index.ts index cd68ab81..1543740d 100644 --- a/src/client/index.ts +++ b/src/client/index.ts @@ -1,3 +1,6 @@ export { useUser } from "./hooks/use-user"; -export { getAccessToken } from "./helpers/get-access-token"; +export { + getAccessToken, + type GetAccessTokenOptions +} from "./helpers/get-access-token"; export { Auth0Provider } from "./providers/auth0-provider"; diff --git a/src/server/auth-client.test.ts b/src/server/auth-client.test.ts index 47415d49..a4569171 100644 --- a/src/server/auth-client.test.ts +++ b/src/server/auth-client.test.ts @@ -3624,6 +3624,88 @@ ca/T0LLtgmbMmxSv/MmzIg== // validate that the session cookie has not been set expect(response.cookies.get("__session")).toBeUndefined(); }); + + it("should force refresh the access token when refresh=true query parameter is provided", async () => { + const currentAccessToken = DEFAULT.accessToken; + const newAccessToken = "at_refreshed_456"; + + const secret = await generateSecret(32); + const transactionStore = new TransactionStore({ + secret + }); + const sessionStore = new StatelessSessionStore({ + secret + }); + const authClient = new AuthClient({ + transactionStore, + sessionStore, + + domain: DEFAULT.domain, + clientId: DEFAULT.clientId, + clientSecret: DEFAULT.clientSecret, + + secret, + appBaseUrl: DEFAULT.appBaseUrl, + + fetch: getMockAuthorizationServer({ + tokenEndpointResponse: { + token_type: "Bearer", + access_token: newAccessToken, + scope: "openid profile email", + expires_in: 86400 // expires in 1 day + } as oauth.TokenEndpointResponse + }) + }); + + // we use a non-expired token to ensure force refresh works even with valid tokens + const expiresAt = Math.floor(Date.now() / 1000) + 10 * 24 * 60 * 60; // expires in 10 days + const session: SessionData = { + user: { + sub: DEFAULT.sub, + name: "John Doe", + email: "john@example.com", + picture: "https://example.com/john.jpg" + }, + tokenSet: { + accessToken: currentAccessToken, + scope: "openid profile email", + refreshToken: DEFAULT.refreshToken, + expiresAt + }, + internal: { + sid: DEFAULT.sid, + createdAt: Math.floor(Date.now() / 1000) + } + }; + const maxAge = 60 * 60; // 1 hour + const expiration = Math.floor(Date.now() / 1000 + maxAge); + const sessionCookie = await encrypt(session, secret, expiration); + const headers = new Headers(); + headers.append("cookie", `__session=${sessionCookie}`); + const request = new NextRequest( + new URL("/auth/access-token?refresh=true", DEFAULT.appBaseUrl), + { + method: "GET", + headers + } + ); + + const response = await authClient.handleAccessToken(request); + expect(response.status).toEqual(200); + expect(await response.json()).toEqual({ + token: newAccessToken, + scope: "openid profile email", + expires_at: expect.any(Number) + }); + + // validate that the session cookie has been updated with the new token + const updatedSessionCookie = response.cookies.get("__session"); + const { payload: updatedSession } = await decrypt( + updatedSessionCookie!.value, + secret + ); + expect(updatedSession.tokenSet.accessToken).toEqual(newAccessToken); + }); }); describe("handleBackChannelLogout", async () => { diff --git a/src/server/auth-client.ts b/src/server/auth-client.ts index dd1b66d3..4c3c84e7 100644 --- a/src/server/auth-client.ts +++ b/src/server/auth-client.ts @@ -590,6 +590,12 @@ export class AuthClient { } async handleAccessToken(req: NextRequest): Promise { + if (!this.enableAccessTokenEndpoint) { + return new NextResponse("Not Found", { + status: 404 + }); + } + const session = await this.sessionStore.get(req.cookies); if (!session) { @@ -606,7 +612,11 @@ export class AuthClient { ); } - const [error, updatedTokenSet] = await this.getTokenSet(session.tokenSet); + const refresh = req.nextUrl.searchParams.get("refresh") === "true"; + const [error, updatedTokenSet] = await this.getTokenSet( + session.tokenSet, + refresh + ); if (error) { return NextResponse.json( From 94cb67ad3cb788c007a498c70943cb557f8dde67 Mon Sep 17 00:00:00 2001 From: Tushar Pandey Date: Wed, 11 Jun 2025 17:58:58 +0530 Subject: [PATCH 2/2] Update src/client/helpers/get-access-token.ts Co-authored-by: Frederik Prijck --- src/client/helpers/get-access-token.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/client/helpers/get-access-token.ts b/src/client/helpers/get-access-token.ts index 4e2f7a03..5015b816 100644 --- a/src/client/helpers/get-access-token.ts +++ b/src/client/helpers/get-access-token.ts @@ -47,7 +47,9 @@ export async function getAccessToken( searchParams.set("refresh", "true"); } - const url = `${process.env.NEXT_PUBLIC_ACCESS_TOKEN_ROUTE || "/auth/access-token"}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`; + const baseUrl = `${process.env.NEXT_PUBLIC_ACCESS_TOKEN_ROUTE}` || "/auth/access-token"; + const queryParams = searchParams.toString() ? `?${searchParams.toString()}` : ""; + const url = `${baseUrl}${queryParams}`; const tokenRes = await fetch(url);