Documentation Suggestion: Validating Permissions in Middleware Securely

[AdrianVvazquez]

Prerequisites

• I have searched the repository’s issues and the Kinde community to ensure my documentation issue isn’t a duplicate
• I have read the contributing guidelines
• I agree to the terms within the code of conduct

How can we improve the docs or what is missing?

Hi Kinde team 👋

While working with the Kinde SDK for Next.js, I noticed that the documentation currently doesn’t cover how to validate permissions inside middleware before the request reaches protected pages. This is essential for many use cases, including role-based access and API-level protection.

I understand that too much internal detail might raise security concerns, but I believe the documentation could offer a recommended pattern to guide developers. For instance:

• How to access session data (like roles or permissions) securely within middleware
• How to use getKindeServerSession() or similar utilities in this context

Thank you for the great work — happy to contribute however I can!

Greetings from Mexico!

Provide extra context, such as what you were trying to do and your requirements

Here’s how I’m currently resolving it, using middleware to enforce role-based access for specific routes:

---

✅ Solution 1 — Using getKindeServerSession()

/routes.ts

export const requiredPermissionsByVisibility = {
  public: [],
  admin: ["access:admin"],
  superadmin: ["access:superadmin"],
} as const;

/middleware.ts

const publicPaths = ["/", "/rifas"];

function getVisibilityForPath(
  path: string
): "public" | "admin" | "superadmin" | null {
  const match = routeAccess
    .sort((a, b) => b.path.length - a.path.length)
    .find((r) => path.startsWith(`${r.path}`));
  return match?.visibility || null;
}

export default withAuth(
  async function middleware(req: NextRequest) {
    const { pathname } = req.nextUrl;
    const { isAuthenticated, getPermissions, getUser } =
      getKindeServerSession();

    const user = await getUser();
    const permissions = await getPermissions();
    const pathVisibility = getVisibilityForPath(pathname);

    if (
      !(await isAuthenticated()) ||
      !user ||
      !pathVisibility ||
      !permissions
    ) {
      return NextResponse.redirect(new URL("/unauthorized", req.url));
    }

    if (pathVisibility === "public") {
      return NextResponse.next();
    }

    const requiredPermissions = requiredPermissionsByVisibility[pathVisibility];

    const hasPermission = requiredPermissions.some((p) =>
      permissions.permissions.includes(p)
    );

    if (!hasPermission) {
      return NextResponse.redirect(new URL("/unauthorized", req.url));
    }

    return NextResponse.next();
  },
  {
    isReturnToCurrentPage: true,
    publicPaths,
  }
);

---

🔄 Solution 2 — Extending NextRequest with kindeAuth

/routes.ts

export const requiredPermissionsByVisibility = {
  public: [],
  admin: ["access:admin"],
  superadmin: ["access:superadmin"],
} as const;

/middleware.ts

const publicPaths = ["/", "/rifas"];

function getVisibilityForPath(
  path: string
): "public" | "admin" | "superadmin" | null {
  const match = routeAccess
    .sort((a, b) => b.path.length - a.path.length)
    .find((r) => path.startsWith(`${r.path}`));
  return match?.visibility || null;
}

interface KindeRequestProps extends NextRequest {
  kindeAuth: { user: KindeUserBase; token: KindeAccessToken };
}

export default withAuth(
  async function middleware(req: KindeRequestProps) {
    const { pathname } = req.nextUrl;
    const kinde = req.kindeAuth;
    const visibility = getVisibilityForPath(pathname);
    const permissions = kinde?.token?.permissions || [];

    if (!visibility || !kinde?.user) {
      return NextResponse.redirect(new URL("/unauthorized", req.url));
    }

    if (visibility === "public") {
      return NextResponse.next();
    }

    const requiredPermissions = requiredPermissionsByVisibility[visibility];

    const hasPermission = requiredPermissions.some((p) =>
      permissions.includes(p)
    );

    if (!hasPermission) {
      return NextResponse.redirect(new URL("/unauthorized", req.url));
    }

    return NextResponse.next();
  },
  {
    isReturnToCurrentPage: true,
    publicPaths,
  }
);

If the docs page already exists, please provide a link

https://docs.kinde.com/developer-tools/sdks/backend/nextjs-sdk/#set-up-middleware

[AdrianVvazquez]

👋 Just wanted to follow up with a potential implementation I tried for permission validation using isAuthorized:

export default withAuth(
  async function middleware(req: NextRequest) {
    return NextResponse.next();
  },
  {
    isReturnToCurrentPage: true,
    publicPaths,
    isAuthorized: ({ req, token }: { req: NextRequest, token: KindeAccessToken }) => {
      const { pathname } = req.nextUrl;
      const visibility = getVisibilityForPath(pathname);
      console.log({ pathname, visibility });

      if (!visibility) return false;
      if (visibility === "public") return true;

      const required = requiredPermissionsByVisibility[visibility] ?? [];
      const userPermissions = token.permissions ?? [];

      return required.some((p) => userPermissions.includes(p));
    },
  }
);

However, this setup led to repeated redirects followed by the following error during the authentication flow:

Error: State not found. To resolve this error please visit our docs https://docs.kinde.com/developer-tools/sdks/backend/nextjs-sdk/#state-not-found-errorAuthentication flow: Received: 77a8f4310ae097785a7940344f60 | Expected: State not found

[DanielRivers]

Hi @AdrianVvazquez,

Thanks for raising this, its a hot topic internally which there was a long discussion about on how to improve route protection across our SDKs, We are honing into an approach which will go some way to addressing the points you're raising.

We will allow you to check roles/permissions/feature flags and elegability from billing all in a simple interface.

You input here is valuable so thank you. Will keep you updated