npm install oidc-spa zodyarn add oidc-spa zodpnpm add oidc-spa zodbun add oidc-spa zodNote: Zod is optional but highly recommended. Writing validators manually is error-prone, and skipping validation means losing early guarantees about what your auth server provides. You can use another validator though, it doesn't have to be Zod.
In Vite apps, this is done through a Vite Plugin (If you'd rather avoid using the Vite plugin checkout the Other SPAs tab).
First rename your entry point file from main.tsx (or main.ts or whatever it is) to main.lazy.tsx
Then create a new index.tsx file:
If you don't have a precise entrypoint that you can simply override, just call oidcEarlyInit as soon as possible and try canceling as much work as possible when shouldLoadApp is false.
You're going to be cloning this example:
React Router v7 has pick the one for you:
IMPORTANT NOTICE:
Because React Router Framwork does not expose a true entrypoint oidc-spa won't let you set enableTokenExfiltrationDefense to true. Since this specific framwork do not give us a way to harden the environement before any other JS is evaluated we can't protect agaist token exfiltration effectively. Note however that even without exfiltration defense, oidc-spa is state of the art in implementing all CBP. You app will pass any security audit.
Now that authentication is handled, there鈥檚 one last piece of the puzzle: your resource server, the backend your app will communicate with.
This can be any type of service: a REST API, tRPC server, or WebSocket endpoint, as long as it can validate access tokens issued by your IdP.
If you鈥檙e building it in JavaScript or TypeScript (for example, using Express), oidc-spa provides ready-to-use utilities to decode and validate access tokens on the server side.
You鈥檒l find the full documentation here:
This is non optional. React Router Framework does not expose the primitives to enable solution like oidc-spa to provide a full stack story. (You may want to give TanStack Start a try, it's the same thing than React Router Framwork but better.w)
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});mv src/main.ts src/main.lazy.tsimport { oidcEarlyInit } from "oidc-spa/entrypoint";
const { shouldLoadApp } = oidcEarlyInit({
// See: https://docs.oidc-spa.dev/resources/token-exfiltration-defence
enableTokenExfiltrationDefense: false,
BASE_URL: "/" // The path where your app is hosted, can also be provided later to createOidc()
});
if (shouldLoadApp) {
// Note: Deferring the main app import adds a few milliseconds to cold start,
// but dramatically speeds up auth. Overall, it's a net win.
import("./index.lazy");
}npx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-declarative rr-declarative-oidc
cd rr-declarative-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev
# Start exploring with: src/oidc.tsnpx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-data rr-data-oidc
cd rr-data-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev
# Start exploring with: src/oidc.tsimport type { Config } from "@react-router/dev/config";
export default {
ssr: false
} satisfies Config;npx gitpick keycloakify/oidc-spa/tree/main/examples/react-router-framework rr-framework-oidc
cd rr-framework-oidc
# You can use our preconfigured Keycloak, Auth0, or Google OAuth test accounts
cp .env.local.sample .env.local
npm install
npm run dev
# Start exploring with: src/oidc.ts