From fb85b0fc8f7235fb6f545caa04e30dbe46c8ca18 Mon Sep 17 00:00:00 2001 From: Bailey Eaton Date: Fri, 20 Dec 2024 23:01:59 +1000 Subject: [PATCH 1/4] feat: update documentation for version 2.5.0 of the Next.js SDK The upcoming 2.5.0 release of the Next.js SDK makes middleware significantly more important - it's now essential for efficient token refreshes. To signify this, the Middleware section has been moved up from the bottom of the page towards the getting started/configuration section and wording has been change to denote that it's now a requirement, not optional. The middleware matchers have been updated to the new 2.5.0 format as well. --- .../sdks/backend/nextjs-sdk.mdx | 178 +++++++++++------- 1 file changed, 109 insertions(+), 69 deletions(-) diff --git a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx index 515bccd7..cf2723a0 100644 --- a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx +++ b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx @@ -76,6 +76,115 @@ This will handle Kinde Auth endpoints in your Next.js app. **Important!** Our SDK relies on this file existing in this location specified above. +## **Set up middleware** + +Middleware is used to protect routes in your Next.js app, and is a requirement for a seamless authentication experience. + +We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. + +We require this middleware to run on all routes beside Next.js internals and static files. The provided matcher will do this for you. + +This means that by default, all routes will be protected. You must opt-out public routes - see [opting routes out of middleware protection](#opting-routes-out-of-middleware-protection) for more information. + + + +#### **Middleware configurations** + +Create a `middleware.ts` file in your projects root directory and add the following code: +```ts +import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware"; + +export default function middleware(req) { + return withAuth(req); +} + +export const config = { + matcher: [ + // Run on everything but Next internals and static files + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + ] +}; +``` + +#### **Route protection with callback function after authorization** + +You can use the `withAuth` helper as shown below with a `middleware` callback function which has access to the `req.kindeAuth` object that exposes the token and user data. + +```ts +import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware"; + +export default withAuth(async function middleware(req) { + console.log("look at me", req.kindeAuth); +}); + +export const config = { + matcher: [ + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + ] +}; +``` + +#### **Opting routes out of middleware protection** + +As the middleware matcher is set to protect all routes, you can opt routes out of middleware protection by adding them to the `publicPaths` array. + +```ts +import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware"; + +export default withAuth( + async function middleware(req) { + }, + { + // Middleware still runs on all routes, but doesn't protect the blog route + publicPaths: ["/blog"], + } +); + +export const config = { + matcher: [ + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + ], +} +``` + +#### **Additional middleware options** + +There are options that can be passed into the middleware function to configure its functionality. + +- `isReturnToCurrentPage` - redirect the user back to the page they were trying to access +- `loginPage` - define the path of the login page (where the users are redirected to when not authenticated) +- `publicPaths` - define the public paths +- `isAuthorized` - define the criteria for authorization + +```ts +import { withAuth } from "@kinde-oss/kinde-auth-nextjs/middleware"; + +export default withAuth( + async function middleware(req) { + console.log("look at me", req.kindeAuth); + }, + { + isReturnToCurrentPage: true, + loginPage: "/login", + publicPaths: ["/public", '/more'], + isAuthorized: ({token}) => { + // The user will be considered authorized if they have the permission 'eat:chips' + return token.permissions.includes("eat:chips"); + } + } +); + +export const config = { + matcher: [ + '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', + ], +} +``` + ## **Set up the Kinde Auth Provider** Wrap your app in the Kinde Auth Provider. This will give you access to the Kinde Auth data in your app and will ensure that the tokens are refreshed when needed. @@ -1340,76 +1449,7 @@ if (!(await isAuthenticated())) { } ``` -### Protect routes using middleware - -You can also protect routes with Next.js middleware. - - - -**Default page protection** - -We provide a `withAuth` helper that will protect routes covered by the matcher. If the user is not authenticated then they are redirected to login and once they have logged in they will be redirected back to the protected page which they should now have access to. - -```jsx -import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware"; -export default function middleware(req) { - return withAuth(req); -} -export const config = { - matcher: ["/admin"] -}; -``` - -**Page protection with callback function after authorization** - -You can use the `withAuth` helper as shown below with a `middleware` callback function which has access to the `req.kindeAuth` object that exposes the token and user data. - -```typescript -import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware"; - -export default withAuth(async function middleware(req) { - console.log("look at me", req.kindeAuth); -}); - -export const config = { - matcher: ["/admin"] -}; -``` - -**Middleware options** - -There are options that can be passed into the middleware function to configure its functionality. -- `isReturnToCurrentPage` - redirect the user back to the page they were trying to access -- `loginPage` - define the path of the login page (where the users are redirected to when not authenticated) -- `publicPaths` - define the public paths -- `isAuthorized` - define the criteria for authorization - -```typescript -import {withAuth} from "@kinde-oss/kinde-auth-nextjs/middleware"; -export default withAuth( - async function middleware(req) { - console.log("look at me", req.kindeAuth); - }, - { - isReturnToCurrentPage: true, - loginPage: "/login", - publicPaths: ["/public", '/more'], - isAuthorized: ({token}) => { - // The user will be considered authorized if they have the permission 'eat:chips' - return token.permissions.includes("eat:chips"); - } - } -); - -export const config = { - matcher: ["/admin"] -}; -``` ## Refreshing Kinde data From 63e2977b77f8bf9ec1256faac65ecbcc4a36ac86 Mon Sep 17 00:00:00 2001 From: Bailey Eaton Date: Fri, 20 Dec 2024 23:10:37 +1000 Subject: [PATCH 2/4] feat: add information about the refresh experience in 2.5.0 Also discuss limitations about the refreshTokens utility in Next.js --- .../sdks/backend/nextjs-sdk.mdx | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx index cf2723a0..845709c8 100644 --- a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx +++ b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx @@ -1453,12 +1453,23 @@ if (!(await isAuthenticated())) { ## Refreshing Kinde data -Kinde data can be updated via the UI or with the Management API. To have these updates be reflected in your app, you will need to get the most up-to-date Kinde data and then refresh the tokens in your session. +Our middleware will automatically refresh the tokens in your session in the background. -To get the most up-to-date Kinde data in your session, use the `refreshTokens` helper function. +Sometimes, you may want to refresh these tokens yourself. An example of this is when you update Kinde data via the UI or with the Management API. -```jsx -const {refreshTokens} = getKindeServerSession(); +To have these updates immediately reflected in your app, you will need to get the most up-to-date Kinde data and then refresh the tokens in your session. + +To get the most up-to-date Kinde data in your session, use the `refreshTokens` helper function provided by `getKindeServerSession`. + + + +```tsx +'use server' +const { refreshTokens } = getKindeServerSession(); const handleRefresh = async () => { await refreshTokens(); From ff7b89defbce5c4983f39a6b2d4122375fbe5c1e Mon Sep 17 00:00:00 2001 From: Bailey Eaton Date: Fri, 20 Dec 2024 23:12:17 +1000 Subject: [PATCH 3/4] chore: formatting --- src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx index 845709c8..a23209cb 100644 --- a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx +++ b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx @@ -1463,7 +1463,9 @@ To get the most up-to-date Kinde data in your session, use the `refreshTokens` h From 592b086bd31018e91e8a17f3740837ffcda4d41f Mon Sep 17 00:00:00 2001 From: Bailey Eaton Date: Sat, 21 Dec 2024 13:26:05 +1000 Subject: [PATCH 4/4] fix: typo --- src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx index a23209cb..81bb193a 100644 --- a/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx +++ b/src/content/docs/developer-tools/sdks/backend/nextjs-sdk.mdx @@ -92,7 +92,7 @@ Want to learn more about middleware? Check out the [Next.js middleware docs](htt -#### **Middleware configurations** +#### **Middleware configuration** Create a `middleware.ts` file in your projects root directory and add the following code: ```ts