import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import viteTsConfigPaths from "vite-tsconfig-paths";
import tailwindcss from "@tailwindcss/vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
tailwindcss(),
tanstackStart(),
oidcSpa(),
viteReact(),
],
});
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});
import { oidcEarlyInit, } from "oidc-spa/entrypoint";
import { oidcSpa } from "oidc-spa/react-spa";
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
});
export const { /* ... */ } = oidcSpa./*...*/
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});
import { oidcEarlyInit, } from "oidc-spa/entrypoint";
import { oidcSpa } from "oidc-spa/react-spa";
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
});
export const { /* ... */ } = oidcSpa./*...*/
import type { Config } from "@react-router/dev/config";
export default {
ssr: false
} satisfies Config;
More context
The server-side validation utilities in oidc-spa implement [RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/rfc9068/). JWT validation works offline.\ There’s no need to contact your authorization server for every request. `oidc-spa/server` fetches the public key published by your IdP once.\ It then uses it to verify that each incoming token: * was signed by the IdP * targets the expected audience * hasn’t expired * has a valid [DPoP proof](broken://spaces/UhNOMoIddws1XoAnT5Nn/pages/AkX224WAW7UAYAoUymBd) (if applicable) This is a big win for edge runtimes.\ Identity and authorization can be established locally, with no external round trips. To authorize certain routes or actions, you can perform additional checks on claims like `groups` or `realm_access.roles`. Some IdPs don’t issue JWT access tokens by default and issue opaque access tokens instead. Opaque access tokens can’t be validated in a provider-agnostic way like JWTs can.\ If your IdP issues opaque access tokens, you’ll need provider-specific tooling.\ In that case, you won’t be able to use `oidc-spa/server`.| Docs | Option |
|---|---|
| /pages/U95czlJaG5VGFSiLaeUm | NestJS |
| /pages/jPYFd1DOgIwEr8YEhJ6x | tRPC |
| /pages/ouqjtmsZVJywv5rMklIc | TanStack Start |
| /pages/D7oSdXrY8PpRNgwq8P0j | Koa |
| /pages/dpMjSkwHciZoaYThM3xK | Fastify |
| /pages/YklVLJe1CNTx5tAEmDL3 | Hono |
| /pages/d1qbPv2oiUEBc6J3j5sN | Express.js |
JS Runtime level integration
| Docs |
|---|
| /pages/8IHPKsisQp1ZEgtiRmTI |
| /pages/d2qm0aCjKdy6kvR8uvUR |
| /pages/vNMUshRNFWPeFKiFOtWv |
| /pages/7iLCD0QZbmGywDt5qJd7 |
| /pages/yfnnatrSBynS6LZmpmMQ |
import express from "express";
import * as fs from "node:fs/promises";
import { z } from "zod";
import { initTRPC } from "@trpc/server";
import { createExpressMiddleware } from "@trpc/server/adapters/express";
import type { Request } from "express";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startExpressTrpcServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = express();
/**
* Key idea: Wether you use use Express or something else
* as underlying HTTP framework, just expose whatever the
* request object representation is to the global context.
* oidc-spa will be able to extract the auth context from it.
*/
const createContext = ({ req }: { req: Request }) => ({ req });
type Context = ReturnType<typeof createContext>;
const t = initTRPC.context<Context>().create();
const appRouter = t.router({
todos: t.procedure.query(async ({ ctx }) => {
const user = await getUser({ req: ctx.req });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
return JSON.parse(json);
}),
todosForSupportStaff: t.procedure
.input(z.object({ userId: z.string() }))
.query(async ({ ctx, input }) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req: ctx.req, requiredRole: "support-staff" });
const json = await fs.readFile(`todos_${input.userId}.json`, "utf8");
return JSON.parse(json);
})
});
app.use(
"/trpc",
// Needed for tRPC POST requests.
express.json(),
createExpressMiddleware({
router: appRouter,
createContext
})
);
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { bootstrapAuth } from "./auth"; // See below
+import { ConfigService } from "@nestjs/config";
async function bootstrap() {
const app = await NestFactory.create(AppModule, /* Any adapter */);
// Requires ConfigModule.forRoot() somewhere in your imports (typically AppModule).
const configService = app.get(ConfigService);
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: configService.get("OIDC_ISSUER_URI")!,
expectedAudience: configService.get("OIDC_AUDIENCE")
});
await app.listen(parseInt(configService.get("PORT") ?? "3000"));
}
bootstrap();
import * as fs from "node:fs/promises";
import { Controller, Get, Param, Req } from "@nestjs/common";
import { getUser } from "./auth";
@Controller("api")
export class TodosController {
@Get("todos")
async getTodos(@Req() req) {
const user = await getUser({ req });
const json = await fs.readFile(`todos_${user.id}.json`, "utf8");
return JSON.parse(json);
}
@Get("todos-for-support/:userId")
async getTodosForSupportStaff(
@Req() req,
@Param("userId") userId: string
) {
// Will reject the request if user making the request
// doesn't have "support-staff" role.
await getUser({ req, requiredRole: "support-staff" });
const json = await fs.readFile(`todos_${userId}.json`, "utf8");
return JSON.parse(json);
}
}
import express from "express";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startExpressServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = express();
app.get("/api/todos", async (req, res) => {
const user = await getUser({ req, res });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
res.status(200).type("application/json").send(json);
});
app.get("/api/todos-for-support/:userId", async (req, res) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, res, requiredRole: "support-staff" });
const json = await fs.readFile(
`todos_${req.params.userId}.json`,
"utf8"
);
res.status(200).type("application/json").send(json);
});
// ...
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import Koa from "koa";
import Router from "@koa/router";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
async function startKoaServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Koa();
const router = new Router();
router.get("/api/todos", async ctx => {
const user = await getUser({ ctx });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
ctx.status = 200;
ctx.type = "application/json";
ctx.body = json;
});
router.get("/api/todos-for-support/:userId", async ctx => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ ctx, requiredRole: "support-staff" });
const json = await fs.readFile(
`todos_${ctx.params.userId}.json`,
"utf8"
);
ctx.status = 200;
ctx.type = "application/json";
ctx.body = json;
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import Fastify from "fastify";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
async function startFastifyServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const fastify = Fastify({
// If you run behind a reverse proxy, you almost always want this enabled.
// It affects things like the computed request origin.
trustProxy: true
});
fastify.get("/api/todos", async (req, reply) => {
const user = await getUser({ req, reply });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
reply.code(200).type("application/json").send(json);
});
fastify.get("/api/todos-for-support/:userId", async (req, reply) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, reply, requiredRole: "support-staff" });
const { userId } = req.params as { userId: string };
const json = await fs.readFile(
`todos_${userId}.json`,
"utf8"
);
reply.code(200).type("application/json").send(json);
});
// ...
await fastify.listen({
port: parseInt(process.env.PORT ?? "3000"),
host: "0.0.0.0"
});
}
import { Hono } from "hono";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startHonoServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Hono();
app.get("/api/todos", async c => {
const user = await getUser({ req: c.req });
const json = await fs.readFile(`todos_${user.id}.json`, "utf8");
return c.text(json);
});
app.get("/api/todos-for-support/:userId", async c => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req: c.req, requiredRole: "support-staff" });
const userId = c.req.param("userId");
const json = await fs.readFile(`todos_${userId}.json`, "utf8");
return c.text(json);
});
// ...
}
import { createServer } from "node:http";
import { parse } from "node:url";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startNodeServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const server = createServer(async (req, res) => {
const { pathname } = parse(req.url!, true);
if (req.method === "GET" && pathname === "/api/todos") {
const user = await getUser({ req, res });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
res.writeHead(200, { "Content-Type": "application/json" });
res.end(json);
return;
}
if (
req.method === "GET" &&
pathname?.startsWith("/api/todos-for-support/")
) {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, res, requiredRole: "support-staff" });
const userId = decodeURIComponent(
pathname.replace("/api/todos-for-support/", "")
);
const json = await fs.readFile(
`todos_${userId}.json`,
"utf8"
);
res.writeHead(200, { "Content-Type": "application/json" });
res.end(json);
return;
}
res.writeHead(404).end();
});
server.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import { bootstrapAuth, getUser } from "./auth.ts"; // See below
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: Deno.env.get("OIDC_ISSUER_URI")!,
expectedAudience: Deno.env.get("OIDC_AUDIENCE") ?? undefined
});
Deno.serve(async (request: Request) => {
const url = new URL(request.url);
if (request.method === "GET" && url.pathname === "/api/todos") {
const user = await getUser({ req: request });
// We got an exception, validation failed
if (user instanceof Response) {
const response = user;
return response;
}
const json = await Deno.readTextFile(
`todos_${user.id}.json`
);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
/**
* Support staff endpoint.
* Example: GET /api/todos/1234
*/
if (request.method === "GET" && url.pathname.startsWith("/api/todos/")) {
let userId: string;
try {
userId = decodeURIComponent(url.pathname.replace("/api/todos/", ""));
} catch {
return new Response("bad request", { status: 400 });
}
if (!userId || userId.includes("/")) {
return new Response("bad request", { status: 400 });
}
{
// Will reject the request if user making the request
// doesn't have "support-staff" role
const user = await getUser({ req: request, requiredRole: "support-staff" });
// We got an exception, validation failed
if (user instanceof Response) {
const response = user;
return response;
}
}
const json = await Deno.readTextFile(`todos_${userId}.json`);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
return new Response("not found", { status: 404 });
});
import { bootstrapAuth, getUser } from "./auth"; // See below
type Env = {
OIDC_ISSUER_URI: string;
OIDC_AUDIENCE?: string;
};
let isBootstrapped = false;
function ensureBootstrapped(env: Env) {
if (isBootstrapped) {
return;
}
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: env.OIDC_ISSUER_URI,
expectedAudience: env.OIDC_AUDIENCE ?? undefined
});
isBootstrapped = true;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
ensureBootstrapped(env);
const url = new URL(request.url);
if (request.method === "GET" && url.pathname === "/api/todos") {
const user = await getUser({ req: request });
// We got a Response, validation failed
if (user instanceof Response) {
return user;
}
// Replace this with KV / D1 / R2 / your DB call.
const json = JSON.stringify([
{ id: "1", label: "Write documentation", ownerId: user.id }
]);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
/**
* Support staff endpoint.
* Example: GET /api/todos-for-support/1234
*/
if (
request.method === "GET" &&
url.pathname.startsWith("/api/todos-for-support/")
) {
let userId: string;
try {
userId = decodeURIComponent(
url.pathname.replace("/api/todos-for-support/", "")
);
} catch {
return new Response("bad request", { status: 400 });
}
if (!userId || userId.includes("/")) {
return new Response("bad request", { status: 400 });
}
{
// Will reject the request if user making the request
// doesn't have "support-staff" role
const user = await getUser({
req: request,
requiredRole: "support-staff"
});
if (user instanceof Response) {
return user;
}
}
// Replace this with KV / D1 / R2 / your DB call.
const json = JSON.stringify([
{ id: "1", label: "Support view", ownerId: userId }
]);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
return new Response("not found", { status: 404 });
}
};
import { Hono } from "hono";
import { createNodeWebSocket } from "@hono/node-ws";
import { serve } from "@hono/node-server";
import { bootstrapAuth, getUser, getUser_ws } from "./auth"; // See below
function startHonoServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Hono();
app.get("/api/todos", async c => { /* ... */ });
const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
app.get(
"/ws",
upgradeWebSocket(async c => {
const user = await getUser_ws({ req: c.req });
return {
onOpen: (_event, ws) => {
ws.send(`Hello ${user.name}`);
},
onMessage(event, ws) {
ws.send(`I'm not very smart, all I can do is repeat: "${event.data}"`);
}
};
})
);
const server = serve({
fetch: app.fetch,
port
});
injectWebSocket(server);
}
import { Evt, type StatefulReadonlyEvt } from "evt";
import { getOidc } from "~/oidc";
import { assert } from "tsafe";
export type Chat = {
evtMessages: StatefulReadonlyEvt<Chat.Message[]>;
sendMessage: (message: string) => void;
};
export namespace Chat {
export type Message = {
origin: "client" | "server";
message: string;
};
}
function createChat(): Chat {
const evtMessages = Evt.create<Chat.Message[]>([]);
const dSocket = Promise.withResolvers<WebSocket>();
(async () => {
const oidc = await getOidc();
assert(oidc.isUserLoggedIn);
const url = new URL(import.meta.env.VITE_TODOS_API_URL); // ex: https://api.my-company.com
url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
url.pathname += "ws";
const socket = new WebSocket(
url.href, // ex: wss://api.my-company.com/ws
// NOTE: This is a common workaround to the fact that the WebSocket API
// does not allow to set custom headers to the UPGRADE request.
// So we use the protocol and on the server read the Sec-WebSocket-Protocol header.
[`authorization_bearer_${await oidc.getAccessToken()}` ]
);
socket.addEventListener("message", event => {
evtMessages.state = [
...evtMessages.state,
{
origin: "server",
message: event.data
}
];
});
socket.addEventListener("error", err => {
console.error("socket error", err);
dSocket.reject(err);
});
socket.addEventListener("open", ()=> {
dSocket.resolve(socket);
});
})();
return {
evtMessages,
sendMessage: async message => {
evtMessages.state = [
...evtMessages.state,
{
origin: "client",
message
}
];
const socket = await dSocket.promise;
socket.send(message);
}
};
}
let chat: Chat | undefined = undefined;
export function getChat() {
if (chat === undefined) {
chat = createChat();
}
return chat;
}
In this screenshot we used auth0.oidc-spa.dev (instead of auth.my-company.com)
bootstrapOidc({
issuerUri: "auth.my-company.com",
clientId: "DzXSmwQS7oSTQGLbafhrPXYLT0mOMyZD"
extraQueryParams: {
audience: "https://app.my-company.com/api"
},
// Auth0 puts DPoP behind a paywall. Explicitely disable it until you have
// enabled it in the Auth0 dashboard.
disableDPoP: true,
// (Optional) This must be kept in sync with the Idle Session Lifetime value
// configured in the Auth0 dashboard. To ensure correct autoLogout behavior.
idleSessionLifetimeInSeconds: 1800,
// ...
});
// In TanStack Start:
.withAccessTokenValidation({
type: "RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens",
expectedAudience: () => "https://app.my-company.com/api",
// ...
})
Example of consent screen you may see in developement but not in production
Hello {user.displayName}!
; } ``` {% endcode %} In browser code outside a React component: {% code title="src/greeting.ts" overflow="wrap" %} ```typescript import { getOidc } from "./oidc"; export async function getGreeting() { const oidc = await getOidc({ assert: "user logged in" }); const { user } = await oidc.getUser(); return `Hello ${user.displayName}!`; } ``` {% endcode %} {% endtab %} {% tab title="Angular" %} {% hint style="info" %} The user abstraction is not available in the Angular adapter yet. {% endhint %} {% endtab %} {% endtabs %} The `user` object is your application's model of the signed-in person. Shape it around what the **frontend needs to render**. ## Implement `createUser` Keep `src/oidc.user.ts` focused on translating identity data into the model consumed by your UI: 1. Define a `User` type containing exactly the information your UI needs. 2. Implement `createUser` to gather that information and return a `User`. Here are some example of the sources you can use to construct the user object. {% tabs %} {% tab title="ID token" %} The decoded payload of the ID token is the simplest source when it already contains everything your UI needs. {% code title="src/oidc.user.ts" overflow="wrap" %} ```typescript import type { CreateUser } from "oidc-spa/core"; import { z } from "zod"; export type User = { displayName: string; email: string | undefined; avatarUrl: string | undefined; }; // Match this schema to the claims guaranteed by your provider. // Available claims depend on its configuration and the requested scopes. const DecodedIdToken = z.object({ name: z.string(), email: z.string().optional(), picture: z.string().optional() }); export const createUser: CreateUserWhat else is available to createUser?
* `decodedIdToken` is the raw decoded ID token payload. Validate the claims your UI depends on, even if you also configured `withExpectedDecodedIdTokenShape()`.
* `accessToken` is the current access token. Use it to call a resource server, but do not store it in `User` because tokens rotate.
* `fetchUserInfo` lazily calls the discovered standard UserInfo endpoint.
* `issuerUri` lets you select provider-specific behavior.
* `user_current` is `undefined` on the first build and contains the previous model during subsequent rebuilds.
`createUser` may return a `User` directly or a promise. Do not call `getUser()` directly or indirectly from inside it: `getUser()` is already waiting for `createUser()` to finish.
import { createOidc } from "oidc-spa/core";
import { createMockOidc } from "oidc-spa/core-mock";
import { createUser, user_mock } from "./oidc.user";
export const prOidc =
import.meta.env.VITE_OIDC_USE_MOCK === "true"
? createMockOidc({
isUserInitiallyLoggedIn: true,
mockedUser: user_mock
})
: createOidc({
issuerUri: import.meta.env.VITE_OIDC_ISSUER_URI,
clientId: import.meta.env.VITE_OIDC_CLIENT_ID,
createUser
});
import { oidcSpa } from "oidc-spa/react-spa";
import { createUser, user_mock, type User } from "./oidc.user";
export const { bootstrapOidc, useOidc, getOidc, /* ... */ } = oidcSpa
.withUser<User>({ createUser, user_mock })
.createUtils();
import { oidcSpa } from "oidc-spa/react-tanstack-start";
import { createUser, user_mock, type User } from "./oidc.user";
export const {
bootstrapOidc,
useOidc,
getOidc,
oidcFnMiddleware,
oidcRequestMiddleware,
/* ... */
} = oidcSpa
.withUser<User>({ createUser, user_mock })
.createUtils();
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import { useOidc } from "@/oidc";
export const Route = createRootRoute({
// ...
shellComponent: ShellComponent,
// NOTE: Even with SSR disabled here, the ShellComponent is still SSR'd.
// Only page components lose SSR.
// You *can* disable SSR per-page for routes that don't load authed data,
// but if your app isn’t public, it’s simpler to SSR only the shell.
ssr: false
});
function ShellComponent({ children }: { children: React.ReactNode }) {
const { isOidcReady } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<div className="min-h-screen flex flex-col">
<Header />
<main className="flex flex-1 flex-col">
{isOidcReady &&
children
}
</main>
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
-
-
- );
-}
+function AuthButtons() {
+
+ const { isOidcReady, logout } = useOidc();
+
+ if (!isOidcReady) {
+ return null;
+ }
+
+ return (
+
+ );
+}
```
{% endcode %}
You can remove the `assert: "user logged in"` from `oidcFnMiddleware` and `oidcRequestMiddleware`:
```diff
-oidcFnMiddleware({ assert: "user logged in" })
+oidcFnMiddleware()
-oidcRequestMiddleware({ assert: "user logged in" })
+oidcRequestMiddleware()
```
You can remove all the beforeLoad: enforceLogin:
```diff
export const Route = createFileRoute("/demo/start/api-request")({
- beforeLoad: enforceLogin,
loader: async () => { },
pendingComponent: () => @Injectable({ providedIn: 'root' })
export class Oidc extends AbstractOidcService<DecodedIdToken> {
// ...
override autoLogin = true;
}
Hello {{ oidc.$decodedIdToken().name }}
-} @else {
-
-
-
-}
```
{% endcode %}
You can remove the usage of Oidc.enforceLoginGuard:
{% code title="src/app/app.routes.ts" %}
```diff
-canActivate: [Oidc.enforceLoginGuard],
//...
canActivate: [
async (route) => {
const oidc = inject(Oidc);
const router = inject(Router);
- await Oidc.enforceLoginGuard(route);
//...
},
],
```
{% endcode %}
{% endtab %}
{% endtabs %}
# Auto Logout
Auto logout is **not** a feature you enable or disable in `oidc-spa`.\
It’s a **policy defined by your Identity Provider (IdP)**.\
What oidc-spa provides is:
* A mechanism to display a feedback overlay that warns users before they’re logged out due to inactivity.
* Ensure they never remain stuck on a stale UI where any interaction would simply redirect them to the login page.
* Monitoring of real user activity across all tabs of your application, ensuring users aren’t mistakenly marked as inactive just because they haven’t performed an action that directly contacts the IdP.
{% embed url="Are you still there?
You will be logged out in {autoLogoutState.secondsLeftBeforeAutoLogout}s
import { AutoLogoutWarningOverlay } from "./components/AutoLogoutWarningOverlay";
export function App() {
return (
<div>
<Header />
<main>{/* ... */}</main>
<AutoLogoutWarningOverlay />
</div>
);
}
Are you still there?
You will be logged out in {{ oidc.$secondsLeftBeforeAutoLogout() }}
@Component({
selector: 'app-root',
templateUrl: './app.html',
})
export class App {
oidc = inject(Oidc);
constructor() {
if (!this.oidc.isUserLoggedIn && this.oidc.initializationError) {
const { initializationError } = this.oidc;
// Helps distinguish a misconfiguration from a temporary auth-server outage.
console.log(initializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with the likely cause and fix.
// Do not display this to end users.
console.log(initializationError.message);
}
}
login() {
if (this.oidc.isUserLoggedIn) {
throw new Error('Control flow error: The user is already logged in');
}
if (this.oidc.initializationError) {
// Keep the UX calm and actionable.
alert("Can't login now, try again later");
return;
}
return this.oidc.login();
}
}
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import { useOidc } from "@/oidc";
import type { OidcInitializationError } from "oidc-spa/core";
export const Route = createRootRoute({
// ...
shellComponent: RootDocument
});
function RootDocument({ children }: { children: React.ReactNode }) {
const { oidcInitializationError } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<div className="min-h-screen flex flex-col">
<Header />
<main className="flex flex-1 flex-col">
{oidcInitializationError ? (
<OidcErrorComponent oidcInitializationError={oidcInitializationError} />
) : (
children
)}
</main>
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
function OidcErrorComponent(props: {
oidcInitializationError: OidcInitializationError;
}){
const { oidcInitializationError } = props;
// Distinguish misconfiguration vs. temporary auth-server outage.
console.log(oidcInitializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(oidcInitializationError.message);
return <h1>Our auth is down, sorry</h1>;
}
import { oidcSpa } from "oidc-spa/react-spa";
export const {
bootstrapOidc,
useOidc,
getOidc,
OidcInitializationGate,
OidcInitializationErrorGate
} = oidcSpa
.withExpectedDecodedIdTokenShape({ /* ... */ }),
.withAutoLogin()
.createUtils();
import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import {
OidcInitializationGate,
OidcInitializationErrorGate
} from "~/oidc";
import type { OidcInitializationError } from "oidc-spa/core";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<OidcInitializationGate>
<OidcInitializationErrorGate errorComponent={OidcErrorComponent} >
<App />
</OidcInitializationErrorGate>
</OidcInitializationGate>
</React.StrictMode>
);
function OidcErrorComponent(props: {
oidcInitializationError: OidcInitializationError;
}){
const { oidcInitializationError } = props;
// Distinguish misconfiguration vs. temporary auth-server outage.
console.log(oidcInitializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(oidcInitializationError.message);
return <h1>Our auth is down, sorry</h1>;
}
Our Auth is down, sorry :(
}@else{ } ``` {% endcode %}@Component({
selector: 'app-root',
imports: [RouterOutlet, RouterLink, RouterLinkActive],
templateUrl: './app.html',
})
export class App {
oidc = inject(Oidc);
constructor(){
if( this.oidc.initializationError ){
const { initializationError } = this.oidc;
// Distinguish a misconfiguration from a temporary auth-server outage.
console.log(initializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(initializationError.message);
}
}
}
import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import { OidcInitializationGate } from "~/oidc";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<OidcInitializationGate>
<App />
</OidcInitializationGate>
</React.StrictMode>
);
import { Suspense } from "react";
import {
useOidc,
OidcInitializationGate
} from "~/oidc";
export function Header() {
return (
<header>
{/* ... */}
<OidcInitializationGate fallback={<Spinner />}>
<AuthButtons />
</OidcInitializationGate>
{/* OR */}
{/*
<Suspense fallback={<Spinner />}>
<AuthButtons />
</Suspense>
*/}
</header>
);
}
function AuthButtons() {
const { isUserLoggedIn } = useOidc();
return (
<div className="animate-fade-in">
{isUserLoggedIn ? <LoggedInAuthButtons /> : <NotLoggedInAuthButtons />}
</div>
);
}
import { withLoginEnforced } from "~/oidc";
// This component can suspend when rendered (like a lazy component would)
// You must define a suspense boundary around it (or use OidcInitializationGate).
const Protected = withLoginEnforced(() => {
return <div>{/* ... */}</div>;
});
export default Protected;
import { lazy, Suspense } from "react";
import { Navigate, Route, Routes } from "react-router";
import { AutoLogoutWarningOverlay } from "./components/AutoLogoutWarningOverlay";
import { Header } from "./components/Header";
import { Home } from "./pages/Home";
const Protected = lazy(() => import("./pages/Protected"));
const AdminOnly = lazy(() => import("./pages/AdminOnly"));
export function App() {
return (
<>
<Header />
<main>
<Suspense fallback={<Spinner />}>
<Routes>
<Route index element={<Home />} />
<Route path="protected" element={<Protected />} />
<Route path="admin-only" element={<AdminOnly />} />
<Route path="*" element={<Navigate to="/" replace />} />
</Routes>
</Suspense>
</main>
<Suspense>
<AutoLogoutWarningOverlay />
</Suspense>
</>
);
}
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { Oidc } from './services/oidc.service';
export const appConfig: ApplicationConfig = {
providers: [
// This will NOT resolve until bootstrapOidc() completes.
Oidc.provide({
// ...
}),
provideRouter(routes),
],
};
// examples/angular-kitchensink/src/app/services/oidc.service.ts
import { Injectable } from '@angular/core';
import { AbstractOidcService } from 'oidc-spa/angular';
@Injectable({ providedIn: 'root' })
export class Oidc extends AbstractOidcService {
// The provider no longer blocks Angular bootstrap
override providerAwaitsInitialization = false;
// ...
}
<!-- examples/angular-kitchensink/src/app/app.html -->
<header>
<span>OIDC-SPA + Angular (Kitchen Sink)</span>
@defer (when oidc.prInitialized | async) {
<!-- Safe to read OIDC values here -->
@if (oidc.isUserLoggedIn) {
<div>
<span>Hello {{ oidc.$decodedIdToken().name }}</span>
<button (click)="oidc.logout({ redirectTo: 'home' })">Logout</button>
</div>
} @else {
<div>
<button (click)="oidc.login()">Login</button>
<button (click)="
oidc.login({
transformUrlBeforeRedirect: keycloakUtils.transformUrlBeforeRedirectForRegister,
})
">
Register
</button>
</div>
}
} @placeholder {
<span style="line-height: 1.35;">Initializing OIDC...</span>
}
</header>
import { Component, inject } from '@angular/core';
import { Oidc } from './services/oidc.service';
import { createKeycloakUtils } from 'oidc-spa/keycloak';
@Component({
selector: 'app-root',
templateUrl: './app.html',
imports: [],
})
export class App {
oidc = inject(Oidc);
// Use a getter so we read issuerUri only after init
get keycloakUtils() {
return createKeycloakUtils({ issuerUri: this.oidc.issuerUri });
}
// Example: drive an "Admin only" link state
get canShowAdminLink(): boolean {
if (!this.oidc.isUserLoggedIn) return true;
const roles = this.oidc.$decodedIdToken().realm_access?.roles ?? [];
return roles.includes('admin');
}
}
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import appCss from "../styles.css?url";
import { useOidc } from "@/oidc";
export const Route = createRootRoute({
head: () => ({ /* ... */ }),
shellComponent: RootDocument
});
function RootDocument({ children }: { children: React.ReactNode }) {
const { isOidcReady } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body
className="min-h-screen text-white"
style={{
backgroundColor: "#0f172a",
backgroundImage: "linear-gradient(180deg, #0f172a 0%, #1e293b 50%, #0f172a 100%)"
}}
>
<div className="min-h-screen flex flex-col">
{isOidcReady && (
<>
<Header />
<main className="flex flex-1 flex-col">
<div className="flex flex-1 flex-col">{children}</div>
</main>
</>
)}
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
{isUserLoggedIn ?
);
}
function Greeting() {
- const { isOidcReady, isUserLoggedIn, decodedIdToken } = useOidc();
+ const { isOidcReady, isUserLoggedIn, decodedIdToken } = useOidc({ assert: "ready" });
- if (!isOidcReady) {
- return <> ;
- }
return (
{isUserLoggedIn ? `Welcome back ${decodedIdToken.name}` : `Hello anonymous visitor!`}
);
}
```
{% endtab %}
{% endtabs %}
# Talking to multiple APIs (with different access tokens)
{% hint style="info" %}
TL;DR
Most apps only need one access token for their backend API.
The rest of this page explains how to talk to multiple APIs securely (Keycloak-style) using oidc-spa.
{% endhint %}
With **oidc-spa**, your **frontend application is the OIDC client**. Your **backend** is **only** a resource server that you call by attaching an `Authorization: Bearer -
{Object.entries(userSecrets).map(([key, value]) => (
- {key}
- {value}
{(()=>{ switch(backFromAuthServer.result["kc_action_status"]){ case "success": return "Password successfully updated"; case "cancelled": return "Password unchanged"; } })()}
)} ); } ``` {% endtab %} {% tab title="Angular" %} ```typescript updatePassword = ()=> this.oidc.goToAuthServer({ extraQueryParams: { kc_action: "UPDATE_PASSWORD" } }); ``` ```angular-html @if( oidc.backFromAuthServer?.extraQueryParams["kc_action"] === "UPDATE_PASSWORD" ){ @if ( oidc.backFromAuthServer.result["kc_action_status"] === "success" ){Password successfully updated
} @else {Password unchanged
} } ``` {% endtab %} {% endtabs %} # User Session Initialization In some cases, you might want to perform some actions when the user login to your app. It might be clearing some storage values, or calling a specific API endpoint.\ If this action is costly. You might want to avoid doing it over and over again each time the user refresh the page. {% tabs %} {% tab title="Vanilla API" %} ```typescript import { createOidc } from "oidc-spa"; const oidc = await createOidc({ /* ... */ }); if (oidc.isUserLoggedIn) { if( oidc.isNewBrowerSession ){ // This is a new visit of the user on your app // or the user signed out and signed in again with // an other identity. await api.onboard(); // (Example) }else{ // It was just a page refresh (Ctrl+R) } } ``` {% endtab %} {% tab title="React API" %} {% code title="src/oidc.ts" %} ```typescript import { createReactOidc } from "oidc-spa/react"; export const { /* ... */ getOidc } = createReactOidc({ /* ... */ }); getOidc().then(oidc => { if( oidc.isNewBrowerSession ){ // This is a new visit of the user on your app // or the user signed out and signed in again with // an other identity. await api.onboard(); // (Example) }else{ // It was just a page refresh (Ctrl+R) } }); ``` {% endcode %} You can also do this in your React component (although it's maybe not the best approach) ```tsx import { useOidc } from "./oidc"; import { useEffect } from "react"; function MyComponent(){ const { isUserLoggedIn, isNewBrowserSession, backFromAuthServer } = useOidc(); useEffect(()=> { if( oidc.isNewBrowerSession ){ // This is a new visit of the user on your app // or the user signed out and signed in again with // an other identity. api.onboard(); // (Example) }else{ // It was just a page refresh (Ctrl+R) } }, []); ``` {% endtab %} {% endtabs %} # Keycloak Utils oidc-spa is provider agnostic.\ You won’t find any Keycloak-only logic in the core package. If you *are* using Keycloak, `oidc-spa/keycloak` exposes small utilities to leverage Keycloak-specific URLs and endpoints. {% hint style="info" %} These utilities are **pure** (no side effects) and only need your `issuerUri`.\ `createKeycloakUtils()` is memoized, so it’s safe to call often. {% endhint %} ### Import ```typescript import { createKeycloakUtils, isKeycloak } from "oidc-spa/keycloak"; ``` ### Optional runtime check: is this issuer Keycloak? Useful when your app can run against multiple providers. ```typescript const oidc = await getOidc(); // or useOidc() or inject(Oidc) if (!isKeycloak({ issuerUri: oidc.issuerUri })) { console.log("The authorization server is not a Keycloak instance"); return; } ``` ### Create the utils object ```typescript const keycloakUtils = createKeycloakUtils({ issuerUri: oidc.issuerUri }); ``` ### Common use cases #### Redirect to the registration page (instead of login) ```typescript oidc.login({ doesCurrentHrefRequiresAuth: false, transformUrlBeforeRedirect: keycloakUtils.transformUrlBeforeRedirectForRegister }); ``` #### Link to the Keycloak Account Console Users can update their profile, password, MFA, sessions, etc. ```typescript const accountUrl = keycloakUtils.getAccountUrl({ clientId: oidc.clientId, validRedirectUri: oidc.validRedirectUri, locale: "en" // Optional }); ``` See: [User Account Management](/features/user-account-management#redirecting-to-your-idps-account-managment-page) #### Fetch the Keycloak user profile (Keycloak-internal endpoint) This is richer than the decoded ID token.\ Equivalent of `keycloak-js` `.loadUserProfile()`. ```typescript const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken const userProfile = await keycloakUtils.fetchUserProfile({ accessToken }); userProfile.id; userProfile.username; userProfile.attributes; ``` #### Fetch user info (OIDC `userinfo` endpoint) Equivalent of `keycloak-js` `.loadUserInfo()`. ```typescript const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken const userInfo = await keycloakUtils.fetchUserInfo({ accessToken }); userInfo.sub; ``` The userInfo object is similarly shaped as what you get if you decode the payload of the access token (which you shouldn't do on the client, see: [JWT Of the Access Token](/resources/jwt-of-the-access-token)) ```typescript import { decodeJwt } from "oidc-spa/decode-jwt"; const decodedAccessToken = decodeJwt(accessToken); ``` #### Admin Console URLs Only show these links to privileged users (for example `realm-admin`). ```typescript keycloakUtils.adminConsoleUrl; // Admin console for the current realm keycloakUtils.adminConsoleUrl_master; // Admin console for the "master" realm ``` ### Parse the issuer URI ```typescript const { issuerUriParsed } = keycloakUtils; // Example issuerUri: // "https://auth.my-company.com/realms/myrealm" issuerUriParsed.origin; // "https://auth.my-company.com" issuerUriParsed.realm; // "myrealm" issuerUriParsed.kcHttpRelativePath; // undefined or "/auth" if the issuer uri was "https://auth.my-company.com/auth/realms/myrealm" ``` # Overview How oidc-spa mitigates the risks of token exposure oidc-spa implements a comprehensive, defense-in-depth strategy to protect against token exfiltration during a successful XSS or supply-chain attack. ## Enabling the defences With oidc-spa, all current best practices are implemented out of the box: * **No persistence**: tokens live in memory only. Sessions are restored by contacting the Authorization server on every app reload. * PKCE is always required and can't be disabled. * Single, non-dynamic [valid redirect URI](#user-content-fn-1)[^1]. (As opposed to keycloak-js, which requires configuring a redirect URI with a wildcard, like| /pages/OQPfLaz21wcSz22qMpf2 |
| /pages/AkX224WAW7UAYAoUymBd |
| /pages/zmd4gn3akUmtOPPYQAXq |
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa({
// ...
browserRuntimeFreeze: {
enabled: true,
// excludes: ["Promise", "fetch", "XMLHttpRequest"]
}
})
]
});
import { oidcEarlyInit } from "oidc-spa/entrypoint";
import { browserRuntimeFreeze } from 'oidc-spa/browser-runtime-freeze';
const { shouldLoadApp } = oidcEarlyInit({
// ...
securityDefenses: {
// ...
...browserRuntimeFreeze({
//excludes: [ "fetch", "XMLHttpRequest", "Promise"]
})
}
});
if (shouldLoadApp) {
import("./main.lazy");
}
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa({
browserRuntimeFreeze: { enabled: true }, // Recommended
DPoP: { enabled: true, mode: "auto" }
})
]
});
import { oidcEarlyInit } from "oidc-spa/entrypoint";
import { browserRuntimeFreeze } from 'oidc-spa/browser-runtime-freeze';
import { DPoP } from 'oidc-spa/DPoP';
const { shouldLoadApp } = oidcEarlyInit({
BASE_URL: "/",
securityDefenses: {
...browserRuntimeFreeze(), // Recommended
...DPoP({ mode: "auto" })
},
});
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("./main.lazy");
}
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa({
// ...
browserRuntimeFreeze: { enabled: true, /*excludes: [...]*/ },//Recommended
tokenSubstitution: {
enabled: true,
// Optional, see below
trustedExternalResourceServers: [
"*.{{location.hostname}}",
"s3.amazonaws.com"
]
}
})
]
});
import { oidcEarlyInit } from "oidc-spa/entrypoint";
import { browserRuntimeFreeze } from 'oidc-spa/browser-runtime-freeze';
import { tokenSubstitution } from 'oidc-spa/token-substitution';
const { shouldLoadApp } = oidcEarlyInit({
BASE_URL: "/",
securityDefenses: {
...browserRuntimeFreeze(/*{ excludes: [...] }*/), // Recommended
...tokenSubstitution({
// Optional, see below
trustedExternalResourceServers: [
`*.${location.hostname}`,
"s3.amazonaws.com"
]
})
}
});
if (shouldLoadApp) {
import("./main.lazy");
}
Why switch?
**Security** * [Enabling DPoP](/security-features/dpop): Keycloak, [starting with 26.4](https://www.keycloak.org/2025/10/dpop-support-26-4), officially supports DPoP. `keycloak-js` doesn’t. * [Browser Runtime Freeze](/security-features/browser-runtime-freeze) * (Optional) [Token Substitution](/security-features/token-substitution) * Static valid redirect URIs: `keycloak-js` forces you to allow wildcard redirects like `https://dashboard.my-company.com/*`. This is [a known attack vector](https://securityblog.omegapoint.se/en/writeup-keycloak-cve-2023-6927/). With `oidc-spa`, the only valid redirect URI is your app’s origin, for example `https://dashboard.my-company.com/`. * Remove all the unsafe knobs that where present in keycloak-js. No footgun. **UX** * [Auto Logout](/features/auto-logout): optional “You will be logged out in 30…29…” overlay. No more “submit → redirect to login” because the Keycloak session expired. * Login/Logout propagation across tabs. * Much faster and relyable SSO, especially in non ideal condition (iframe blocked / Keycloak not on same site, slow network...)import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa({
// See: https://docs.oidc-spa.dev/v/v10/security-features/browser-runtime-freeze
browserRuntimeFreeze: {
enabled: true
//excludes: [ "fetch", "XMLHttpRequest"]
},
// See: https://docs.oidc-spa.dev/v/v10/security-features/dpop
DPoP: {
enabled: true,
mode: "auto"
}
})
]
});
import { Keycloak } from "oidc-spa/keycloak-js";
import { oidcEarlyInit } from "oidc-spa/entrypoint";
import { browserRuntimeFreeze } from 'oidc-spa/browser-runtime-freeze';
import { DPoP } from 'oidc-spa/DPoP';
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
// If applicable you should use `process.env.PUBLIC_URL`
// or `import.meta.env.BASE_URL`.
// This is not an option. There's only one good answer.
securityDefenses: {
// See: https://docs.oidc-spa.dev/v/v10/security-features/browser-runtime-freeze
...browserRuntimeFreeze({
//excludes: [ "fetch", "XMLHttpRequest" ]
}),
// See: https://docs.oidc-spa.dev/v/v10/security-features/dpop
...DPoP({ mode: 'auto' })
}
});
const keycloak = new Keycloak({ /* ... */ });
export default defineConfig({
plugins: [
// ...
oidcSpa({
// "auto" (default) | "iframe" | "full page redirect"
sessionRestorationMethod: "auto"
}),
]
});
# Assuming nginxinc/nginx-unprivileged
# ============================================================
# Dynamic base domain extraction (per request)
# Example: dashboard.my-company.com -> my-company.com
# ============================================================
map $host $base_domain {
~^(?<sub>.+)\.(?<domain>[^.]+\.[^.]+)$ $domain;
default $host;
}
server {
listen 8080;
# -------------------------
# Gzip
# -------------------------
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_proxied expired no-cache no-store private auth;
gzip_types
text/plain text/css text/xml text/javascript
application/javascript application/x-javascript application/xml;
gzip_disable "MSIE [1-6]\.";
# -------------------------
# Root and SPA routing
# -------------------------
root /usr/share/nginx/html;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# -------------------------
# Vite hashed assets (cache 1 year)
# -------------------------
location ^~ /assets/ {
try_files $uri =404;
expires 1y;
access_log off;
add_header Cache-Control "public" always;
}
# -------------------------
# HTML (never cached) + CSP
# -------------------------
location ~* \.html$ {
try_files $uri =404;
expires -1;
add_header Content-Security-Policy "
frame-src https://*.$base_domain;
frame-ancestors 'self';
object-src 'none';
worker-src 'none';
script-src 'self' 'strict-dynamic';
" always;
}
# -------------------------
# JSON / TXT (never cached)
# -------------------------
location ~* \.(json|txt)$ {
try_files $uri =404;
expires -1;
}
# -------------------------
# Any other file with an extension (cache 1 day)
# -------------------------
location ~ ^.+\..+$ {
try_files $uri =404;
expires 1d;
access_log off;
add_header Cache-Control "public" always;
}
}
| Browser-Side OIDC | Server-Side OIDC | |
|---|---|---|
| Implementation | oidc-spa, keycloak-js, angular-oauth2-oidc, react-oidc-context, @auth0/auth0-spa-js, @azure/msal-browser, @axa-fr/oidc-client, oidc-client-ts (without client secret) | nuxt-oidc-auth, oidc-client-ts (with client secret), NextAuth/Auth.js/BetterAuth (often “roll your own auth” frameworks that can broker OIDC providers) |
| OIDC Model | The frontend is the OIDC client. Your backend API is an OAuth resource server. The frontend calls the API with an access token. The API can validate the token signature and resolve identity offline. | The backend is the OIDC client. User identity is tracked with session cookies. In this model, there is usually no OAuth resource server. Access tokens are mainly used for calling third-party APIs. |
| Infrastructure Requirement | None. The browser talks directly to the authorization server. | Requires a stateful backend and a shared session store (e.g. Redis). |
| Setup | Simple. Auth is decoupled from your app framework, router, and API. | Tightly coupled to a framework. You typically build login/logout routes and middleware. |
| Security | Historically weaker because tokens exist in the browser. With DPoP and modern defenses, the security gap can shrink significantly. See details. | Secure by design. Tokens are not exposed to frontend code. |
| Server-side rendering | Limited. The server renders without user context. Auth-aware UI renders on the client. | Seamless. The server knows who the user is during render. |
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});
import {
oidcEarlyInit,
createOidc
} from "oidc-spa/core";
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
});
const prOidc = createOidc({ /* ... See below ... */ });
export async function getOidc(){
const oidc = await prOidc;
return oidc;
}
import { createOidc } from "oidc-spa/core";
import { createMockOidc } from "oidc-spa/core-mock";
import { z } from "zod";
const decodedIdTokenSchema = z.object({
sub: z.string(),
preferred_username: z.string()
});
const autoLogin = false;
const prOidc = !import.meta.env.VITE_OIDC_ISSUER
? createMockOidc({
// NOTE: If autoLogin is set to true this option must be removed
isUserInitiallyLoggedIn: false,
mockedTokens: {
decodedIdToken: {
sub: "123",
preferred_username: "john doe"
} satisfies z.infer<typeof decodedIdTokenSchema>
},
autoLogin
})
: createOidc({
issuerUri: import.meta.env.VITE_OIDC_ISSUER,
clientId: import.meta.env.VITE_OIDC_CLIENT_ID,
decodedIdTokenSchema,
autoLogin
});
import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import viteTsConfigPaths from "vite-tsconfig-paths";
import tailwindcss from "@tailwindcss/vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
tailwindcss(),
tanstackStart(),
oidcSpa(),
viteReact(),
],
});
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});
import { oidcEarlyInit, } from "oidc-spa/entrypoint";
import { oidcSpa } from "oidc-spa/react-spa";
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
});
export const { /* ... */ } = oidcSpa./*...*/
import { defineConfig } from "vite";
import { oidcSpa } from "oidc-spa/vite-plugin";
export default defineConfig({
plugins: [
// ...
oidcSpa()
]
});
import { oidcEarlyInit, } from "oidc-spa/entrypoint";
import { oidcSpa } from "oidc-spa/react-spa";
// Should run as early as possible.
oidcEarlyInit({
BASE_URL: "/" // The path where your app is hosted
});
export const { /* ... */ } = oidcSpa./*...*/
import type { Config } from "@react-router/dev/config";
export default {
ssr: false
} satisfies Config;
More context
The server-side validation utilities in oidc-spa implement [RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/rfc9068/). JWT validation works offline.\ There’s no need to contact your authorization server for every request. `oidc-spa/server` fetches the public key published by your IdP once.\ It then uses it to verify that each incoming token: * was signed by the IdP * targets the expected audience * hasn’t expired * has a valid [DPoP proof](broken://spaces/UhNOMoIddws1XoAnT5Nn/pages/AkX224WAW7UAYAoUymBd) (if applicable) This is a big win for edge runtimes.\ Identity and authorization can be established locally, with no external round trips. To authorize certain routes or actions, you can perform additional checks on claims like `groups` or `realm_access.roles`. Some IdPs don’t issue JWT access tokens by default and issue opaque access tokens instead. Opaque access tokens can’t be validated in a provider-agnostic way like JWTs can.\ If your IdP issues opaque access tokens, you’ll need provider-specific tooling.\ In that case, you won’t be able to use `oidc-spa/server`.| Docs | Option |
|---|---|
| /pages/U95czlJaG5VGFSiLaeUm | NestJS |
| /pages/jPYFd1DOgIwEr8YEhJ6x | tRPC |
| /pages/ouqjtmsZVJywv5rMklIc | TanStack Start |
| /pages/D7oSdXrY8PpRNgwq8P0j | Koa |
| /pages/dpMjSkwHciZoaYThM3xK | Fastify |
| /pages/YklVLJe1CNTx5tAEmDL3 | Hono |
| /pages/d1qbPv2oiUEBc6J3j5sN | Express.js |
JS Runtime level integration
| Docs |
|---|
| /pages/8IHPKsisQp1ZEgtiRmTI |
| /pages/d2qm0aCjKdy6kvR8uvUR |
| /pages/vNMUshRNFWPeFKiFOtWv |
| /pages/7iLCD0QZbmGywDt5qJd7 |
| /pages/yfnnatrSBynS6LZmpmMQ |
import express from "express";
import * as fs from "node:fs/promises";
import { z } from "zod";
import { initTRPC } from "@trpc/server";
import { createExpressMiddleware } from "@trpc/server/adapters/express";
import type { Request } from "express";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startExpressTrpcServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = express();
/**
* Key idea: Wether you use use Express or something else
* as underlying HTTP framework, just expose whatever the
* request object representation is to the global context.
* oidc-spa will be able to extract the auth context from it.
*/
const createContext = ({ req }: { req: Request }) => ({ req });
type Context = ReturnType<typeof createContext>;
const t = initTRPC.context<Context>().create();
const appRouter = t.router({
todos: t.procedure.query(async ({ ctx }) => {
const user = await getUser({ req: ctx.req });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
return JSON.parse(json);
}),
todosForSupportStaff: t.procedure
.input(z.object({ userId: z.string() }))
.query(async ({ ctx, input }) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req: ctx.req, requiredRole: "support-staff" });
const json = await fs.readFile(`todos_${input.userId}.json`, "utf8");
return JSON.parse(json);
})
});
app.use(
"/trpc",
// Needed for tRPC POST requests.
express.json(),
createExpressMiddleware({
router: appRouter,
createContext
})
);
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { bootstrapAuth } from "./auth"; // See below
+import { ConfigService } from "@nestjs/config";
async function bootstrap() {
const app = await NestFactory.create(AppModule, /* Any adapter */);
// Requires ConfigModule.forRoot() somewhere in your imports (typically AppModule).
const configService = app.get(ConfigService);
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: configService.get("OIDC_ISSUER_URI")!,
expectedAudience: configService.get("OIDC_AUDIENCE")
});
await app.listen(parseInt(configService.get("PORT") ?? "3000"));
}
bootstrap();
import * as fs from "node:fs/promises";
import { Controller, Get, Param, Req } from "@nestjs/common";
import { getUser } from "./auth";
@Controller("api")
export class TodosController {
@Get("todos")
async getTodos(@Req() req) {
const user = await getUser({ req });
const json = await fs.readFile(`todos_${user.id}.json`, "utf8");
return JSON.parse(json);
}
@Get("todos-for-support/:userId")
async getTodosForSupportStaff(
@Req() req,
@Param("userId") userId: string
) {
// Will reject the request if user making the request
// doesn't have "support-staff" role.
await getUser({ req, requiredRole: "support-staff" });
const json = await fs.readFile(`todos_${userId}.json`, "utf8");
return JSON.parse(json);
}
}
import express from "express";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startExpressServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = express();
app.get("/api/todos", async (req, res) => {
const user = await getUser({ req, res });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
res.status(200).type("application/json").send(json);
});
app.get("/api/todos-for-support/:userId", async (req, res) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, res, requiredRole: "support-staff" });
const json = await fs.readFile(
`todos_${req.params.userId}.json`,
"utf8"
);
res.status(200).type("application/json").send(json);
});
// ...
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import Koa from "koa";
import Router from "@koa/router";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
async function startKoaServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Koa();
const router = new Router();
router.get("/api/todos", async ctx => {
const user = await getUser({ ctx });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
ctx.status = 200;
ctx.type = "application/json";
ctx.body = json;
});
router.get("/api/todos-for-support/:userId", async ctx => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ ctx, requiredRole: "support-staff" });
const json = await fs.readFile(
`todos_${ctx.params.userId}.json`,
"utf8"
);
ctx.status = 200;
ctx.type = "application/json";
ctx.body = json;
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import Fastify from "fastify";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
async function startFastifyServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const fastify = Fastify({
// If you run behind a reverse proxy, you almost always want this enabled.
// It affects things like the computed request origin.
trustProxy: true
});
fastify.get("/api/todos", async (req, reply) => {
const user = await getUser({ req, reply });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
reply.code(200).type("application/json").send(json);
});
fastify.get("/api/todos-for-support/:userId", async (req, reply) => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, reply, requiredRole: "support-staff" });
const { userId } = req.params as { userId: string };
const json = await fs.readFile(
`todos_${userId}.json`,
"utf8"
);
reply.code(200).type("application/json").send(json);
});
// ...
await fastify.listen({
port: parseInt(process.env.PORT ?? "3000"),
host: "0.0.0.0"
});
}
import { Hono } from "hono";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startHonoServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Hono();
app.get("/api/todos", async c => {
const user = await getUser({ req: c.req });
const json = await fs.readFile(`todos_${user.id}.json`, "utf8");
return c.text(json);
});
app.get("/api/todos-for-support/:userId", async c => {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req: c.req, requiredRole: "support-staff" });
const userId = c.req.param("userId");
const json = await fs.readFile(`todos_${userId}.json`, "utf8");
return c.text(json);
});
// ...
}
import { createServer } from "node:http";
import { parse } from "node:url";
import * as fs from "node:fs/promises";
import { bootstrapAuth, getUser } from "./auth"; // See below
function startNodeServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const server = createServer(async (req, res) => {
const { pathname } = parse(req.url!, true);
if (req.method === "GET" && pathname === "/api/todos") {
const user = await getUser({ req, res });
const json = await fs.readFile(
`todos_${user.id}.json`,
"utf8"
);
res.writeHead(200, { "Content-Type": "application/json" });
res.end(json);
return;
}
if (
req.method === "GET" &&
pathname?.startsWith("/api/todos-for-support/")
) {
// Will reject the request if user making the request
// doesn't have "support-staff" role
await getUser({ req, res, requiredRole: "support-staff" });
const userId = decodeURIComponent(
pathname.replace("/api/todos-for-support/", "")
);
const json = await fs.readFile(
`todos_${userId}.json`,
"utf8"
);
res.writeHead(200, { "Content-Type": "application/json" });
res.end(json);
return;
}
res.writeHead(404).end();
});
server.listen(parseInt(process.env.PORT ?? "3000"), () => {
console.log("Server running");
});
}
import { bootstrapAuth, getUser } from "./auth.ts"; // See below
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: Deno.env.get("OIDC_ISSUER_URI")!,
expectedAudience: Deno.env.get("OIDC_AUDIENCE") ?? undefined
});
Deno.serve(async (request: Request) => {
const url = new URL(request.url);
if (request.method === "GET" && url.pathname === "/api/todos") {
const user = await getUser({ req: request });
// We got an exception, validation failed
if (user instanceof Response) {
const response = user;
return response;
}
const json = await Deno.readTextFile(
`todos_${user.id}.json`
);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
/**
* Support staff endpoint.
* Example: GET /api/todos/1234
*/
if (request.method === "GET" && url.pathname.startsWith("/api/todos/")) {
let userId: string;
try {
userId = decodeURIComponent(url.pathname.replace("/api/todos/", ""));
} catch {
return new Response("bad request", { status: 400 });
}
if (!userId || userId.includes("/")) {
return new Response("bad request", { status: 400 });
}
{
// Will reject the request if user making the request
// doesn't have "support-staff" role
const user = await getUser({ req: request, requiredRole: "support-staff" });
// We got an exception, validation failed
if (user instanceof Response) {
const response = user;
return response;
}
}
const json = await Deno.readTextFile(`todos_${userId}.json`);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
return new Response("not found", { status: 404 });
});
import { bootstrapAuth, getUser } from "./auth"; // See below
type Env = {
OIDC_ISSUER_URI: string;
OIDC_AUDIENCE?: string;
};
let isBootstrapped = false;
function ensureBootstrapped(env: Env) {
if (isBootstrapped) {
return;
}
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: env.OIDC_ISSUER_URI,
expectedAudience: env.OIDC_AUDIENCE ?? undefined
});
isBootstrapped = true;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
ensureBootstrapped(env);
const url = new URL(request.url);
if (request.method === "GET" && url.pathname === "/api/todos") {
const user = await getUser({ req: request });
// We got a Response, validation failed
if (user instanceof Response) {
return user;
}
// Replace this with KV / D1 / R2 / your DB call.
const json = JSON.stringify([
{ id: "1", label: "Write documentation", ownerId: user.id }
]);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
/**
* Support staff endpoint.
* Example: GET /api/todos-for-support/1234
*/
if (
request.method === "GET" &&
url.pathname.startsWith("/api/todos-for-support/")
) {
let userId: string;
try {
userId = decodeURIComponent(
url.pathname.replace("/api/todos-for-support/", "")
);
} catch {
return new Response("bad request", { status: 400 });
}
if (!userId || userId.includes("/")) {
return new Response("bad request", { status: 400 });
}
{
// Will reject the request if user making the request
// doesn't have "support-staff" role
const user = await getUser({
req: request,
requiredRole: "support-staff"
});
if (user instanceof Response) {
return user;
}
}
// Replace this with KV / D1 / R2 / your DB call.
const json = JSON.stringify([
{ id: "1", label: "Support view", ownerId: userId }
]);
return new Response(json, {
status: 200,
headers: { "content-type": "application/json" }
});
}
return new Response("not found", { status: 404 });
}
};
import { Hono } from "hono";
import { createNodeWebSocket } from "@hono/node-ws";
import { serve } from "@hono/node-server";
import { bootstrapAuth, getUser, getUser_ws } from "./auth"; // See below
function startHonoServer() {
bootstrapAuth({
implementation: "real", // or "mock", see: https://docs.oidc-spa.dev/v/v8/integration-guides/backend-token-validation/mock-modes
issuerUri: process.env.OIDC_ISSUER_URI!,
expectedAudience: process.env.OIDC_AUDIENCE
});
const app = new Hono();
app.get("/api/todos", async c => { /* ... */ });
const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
app.get(
"/ws",
upgradeWebSocket(async c => {
const user = await getUser_ws({ req: c.req });
return {
onOpen: (_event, ws) => {
ws.send(`Hello ${user.name}`);
},
onMessage(event, ws) {
ws.send(`I'm not very smart, all I can do is repeat: "${event.data}"`);
}
};
})
);
const server = serve({
fetch: app.fetch,
port
});
injectWebSocket(server);
}
import { Evt, type StatefulReadonlyEvt } from "evt";
import { getOidc } from "~/oidc";
import { assert } from "tsafe";
export type Chat = {
evtMessages: StatefulReadonlyEvt<Chat.Message[]>;
sendMessage: (message: string) => void;
};
export namespace Chat {
export type Message = {
origin: "client" | "server";
message: string;
};
}
function createChat(): Chat {
const evtMessages = Evt.create<Chat.Message[]>([]);
const dSocket = Promise.withResolvers<WebSocket>();
(async () => {
const oidc = await getOidc();
assert(oidc.isUserLoggedIn);
const url = new URL(import.meta.env.VITE_TODOS_API_URL); // ex: https://api.my-company.com
url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
url.pathname += "ws";
const socket = new WebSocket(
url.href, // ex: wss://api.my-company.com/ws
// NOTE: This is a common workaround to the fact that the WebSocket API
// does not allow to set custom headers to the UPGRADE request.
// So we use the protocol and on the server read the Sec-WebSocket-Protocol header.
[`authorization_bearer_${await oidc.getAccessToken()}` ]
);
socket.addEventListener("message", event => {
evtMessages.state = [
...evtMessages.state,
{
origin: "server",
message: event.data
}
];
});
socket.addEventListener("error", err => {
console.error("socket error", err);
dSocket.reject(err);
});
socket.addEventListener("open", ()=> {
dSocket.resolve(socket);
});
})();
return {
evtMessages,
sendMessage: async message => {
evtMessages.state = [
...evtMessages.state,
{
origin: "client",
message
}
];
const socket = await dSocket.promise;
socket.send(message);
}
};
}
let chat: Chat | undefined = undefined;
export function getChat() {
if (chat === undefined) {
chat = createChat();
}
return chat;
}
const { ... } = createOidc({
issuerUri: "dev-r2h8076n6dns3d4y.us.auth0.com",
clientId: "DzXSmwQS7oSTQGLbafhrPXYLT0mOMyZD",
extraQueryParams: {
audience: "https://app.my-company.com/api"
}
});
const { ... } = createOidc({
issuerUri: "auth.my-company.com",
clientId: "DzXSmwQS7oSTQGLbafhrPXYLT0mOMyZD",
extraQueryParams: {
audience: "https://app.my-company.com/api"
},
idleSessionLifetimeInSeconds: 300
});
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import { useOidc } from "@/oidc";
export const Route = createRootRoute({
// ...
shellComponent: ShellComponent,
// NOTE: Even with SSR disabled here, the ShellComponent is still SSR'd.
// Only page components lose SSR.
// You *can* disable SSR per-page for routes that load authed data,
// but if your app isn’t public, it’s simpler to SSR only the shell.
ssr: false
});
function ShellComponent({ children }: { children: React.ReactNode }) {
const { isOidcReady } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<div className="min-h-screen flex flex-col">
<Header />
<main className="flex flex-1 flex-col">
{isOidcReady &&
children
}
</main>
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
-
-
- );
-}
+function AuthButtons() {
+
+ const { isOidcReady, logout } = useOidc();
+
+ if (!isOidcReady) {
+ return null;
+ }
+
+ return (
+
+ );
+}
```
{% endcode %}
You can remove the `assert: "user logged in"` from `oidcFnMiddleware` and `oidcRequestMiddleware`:
```diff
-oidcFnMiddleware({ assert: "user logged in" })
+oidcFnMiddleware()
-oidcRequestMiddleware({ assert: "user logged in" })
+oidcRequestMiddleware()
```
You can remove all the beforeLoad: enforceLogin:
```diff
export const Route = createFileRoute("/demo/start/api-request")({
- beforeLoad: enforceLogin,
loader: async () => { },
pendingComponent: () => @Injectable({ providedIn: 'root' })
export class Oidc extends AbstractOidcService<DecodedIdToken> {
// ...
override autoLogin = true;
}
Hello {{ oidc.$decodedIdToken().name }}
-} @else {
-
-
-
-}
```
{% endcode %}
You can remove the usage of Oidc.enforceLoginGuard:
{% code title="src/app/app.routes.ts" %}
```diff
-canActivate: [Oidc.enforceLoginGuard],
//...
canActivate: [
async (route) => {
const oidc = inject(Oidc);
const router = inject(Router);
- await Oidc.enforceLoginGuard(route);
//...
},
],
```
{% endcode %}
{% endtab %}
{% endtabs %}
# Auto Logout
Auto logout is **not** a feature you enable or disable in `oidc-spa`.\
It’s a **policy defined by your Identity Provider (IdP)**.\
What oidc-spa provides is:
* A mechanism to display a feedback overlay that warns users before they’re logged out due to inactivity.
* Ensure they never remain stuck on a stale UI where any interaction would simply redirect them to the login page.
* Monitoring of real user activity across all tabs of your application, ensuring users aren’t mistakenly marked as inactive just because they haven’t performed an action that directly contacts the IdP.
{% embed url="Are you still there?
You will be logged out in {autoLogoutState.secondsLeftBeforeAutoLogout}s
import { AutoLogoutWarningOverlay } from "./components/AutoLogoutWarningOverlay";
export function App() {
return (
<div>
<Header />
<main>{/* ... */}</main>
<AutoLogoutWarningOverlay />
</div>
);
}
Are you still there?
You will be logged out in {{ oidc.$secondsLeftBeforeAutoLogout() }}
@Component({
selector: 'app-root',
templateUrl: './app.html',
})
export class App {
oidc = inject(Oidc);
constructor() {
if (!this.oidc.isUserLoggedIn && this.oidc.initializationError) {
const { initializationError } = this.oidc;
// Helps distinguish a misconfiguration from a temporary auth-server outage.
console.log(initializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with the likely cause and fix.
// Do not display this to end users.
console.log(initializationError.message);
}
}
login() {
if (this.oidc.isUserLoggedIn) {
throw new Error('Control flow error: The user is already logged in');
}
if (this.oidc.initializationError) {
// Keep the UX calm and actionable.
alert("Can't login now, try again later");
return;
}
return this.oidc.login();
}
}
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import { useOidc } from "@/oidc";
import type { OidcInitializationError } from "oidc-spa/core";
export const Route = createRootRoute({
// ...
shellComponent: RootDocument
});
function RootDocument({ children }: { children: React.ReactNode }) {
const { oidcInitializationError } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body>
<div className="min-h-screen flex flex-col">
<Header />
<main className="flex flex-1 flex-col">
{oidcInitializationError ? (
<OidcErrorComponent oidcInitializationError={oidcInitializationError} />
) : (
children
)}
</main>
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
function OidcErrorComponent(props: {
oidcInitializationError: OidcInitializationError;
}){
const { oidcInitializationError } = props;
// Distinguish misconfiguration vs. temporary auth-server outage.
console.log(oidcInitializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(oidcInitializationError.message);
return <h1>Our auth is down, sorry</h1>;
}
import { oidcSpa } from "oidc-spa/react-spa";
export const {
bootstrapOidc,
useOidc,
getOidc,
OidcInitializationGate,
OidcInitializationErrorGate
} = oidcSpa
.withExpectedDecodedIdTokenShape({ /* ... */ }),
.withAutoLogin()
.createUtils();
import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import {
OidcInitializationGate,
OidcInitializationErrorGate
} from "~/oidc";
import type { OidcInitializationError } from "oidc-spa/core";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<OidcInitializationGate>
<OidcInitializationErrorGate errorComponent={OidcErrorComponent} >
<App />
</OidcInitializationErrorGate>
</OidcInitializationGate>
</React.StrictMode>
);
function OidcErrorComponent(props: {
oidcInitializationError: OidcInitializationError;
}){
const { oidcInitializationError } = props;
// Distinguish misconfiguration vs. temporary auth-server outage.
console.log(oidcInitializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(oidcInitializationError.message);
return <h1>Our auth is down, sorry</h1>;
}
Our Auth is down, sorry :(
}@else{ } ``` {% endcode %}@Component({
selector: 'app-root',
imports: [RouterOutlet, RouterLink, RouterLinkActive],
templateUrl: './app.html',
})
export class App {
oidc = inject(Oidc);
constructor(){
if( this.oidc.initializationError ){
const { initializationError } = this.oidc;
// Distinguish a misconfiguration from a temporary auth-server outage.
console.log(initializationError.isAuthServerLikelyDown);
// Developer-only diagnostic with likely cause and fix.
// Do not display this to end users.
console.log(initializationError.message);
}
}
}
import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App";
import { OidcInitializationGate } from "~/oidc";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<OidcInitializationGate>
<App />
</OidcInitializationGate>
</React.StrictMode>
);
import { Suspense } from "react";
import {
useOidc,
OidcInitializationGate
} from "~/oidc";
export function Header() {
return (
<header>
{/* ... */}
<OidcInitializationGate fallback={<Spinner />}>
<AuthButtons />
</OidcInitializationGate>
{/* OR */}
{/*
<Suspense fallback={<Spinner />}>
<AuthButtons />
</Suspense>
*/}
</header>
);
}
function AuthButtons() {
const { isUserLoggedIn } = useOidc();
return (
<div className="animate-fade-in">
{isUserLoggedIn ? <LoggedInAuthButtons /> : <NotLoggedInAuthButtons />}
</div>
);
}
import { withLoginEnforced } from "~/oidc";
// This component can suspend when rendered (like a lazy component would)
// You must define a suspense boundary around it (or use OidcInitializationGate).
const Protected = withLoginEnforced(() => {
return <div>{/* ... */}</div>;
});
export default Protected;
import { lazy, Suspense } from "react";
import { Navigate, Route, Routes } from "react-router";
import { AutoLogoutWarningOverlay } from "./components/AutoLogoutWarningOverlay";
import { Header } from "./components/Header";
import { Home } from "./pages/Home";
const Protected = lazy(() => import("./pages/Protected"));
const AdminOnly = lazy(() => import("./pages/AdminOnly"));
export function App() {
return (
<>
<Header />
<main>
<Suspense fallback={<Spinner />}>
<Routes>
<Route index element={<Home />} />
<Route path="protected" element={<Protected />} />
<Route path="admin-only" element={<AdminOnly />} />
<Route path="*" element={<Navigate to="/" replace />} />
</Routes>
</Suspense>
</main>
<Suspense>
<AutoLogoutWarningOverlay />
</Suspense>
</>
);
}
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { Oidc } from './services/oidc.service';
export const appConfig: ApplicationConfig = {
providers: [
// This will NOT resolve until bootstrapOidc() completes.
Oidc.provide({
// ...
}),
provideRouter(routes),
],
};
// examples/angular-kitchensink/src/app/services/oidc.service.ts
import { Injectable } from '@angular/core';
import { AbstractOidcService } from 'oidc-spa/angular';
@Injectable({ providedIn: 'root' })
export class Oidc extends AbstractOidcService {
// The provider no longer blocks Angular bootstrap
override providerAwaitsInitialization = false;
// ...
}
<!-- examples/angular-kitchensink/src/app/app.html -->
<header>
<span>OIDC-SPA + Angular (Kitchen Sink)</span>
@defer (when oidc.prInitialized | async) {
<!-- Safe to read OIDC values here -->
@if (oidc.isUserLoggedIn) {
<div>
<span>Hello {{ oidc.$decodedIdToken().name }}</span>
<button (click)="oidc.logout({ redirectTo: 'home' })">Logout</button>
</div>
} @else {
<div>
<button (click)="oidc.login()">Login</button>
<button (click)="
oidc.login({
transformUrlBeforeRedirect: keycloakUtils.transformUrlBeforeRedirectForRegister,
})
">
Register
</button>
</div>
}
} @placeholder {
<span style="line-height: 1.35;">Initializing OIDC...</span>
}
</header>
import { Component, inject } from '@angular/core';
import { Oidc } from './services/oidc.service';
import { createKeycloakUtils } from 'oidc-spa/keycloak';
@Component({
selector: 'app-root',
templateUrl: './app.html',
imports: [],
})
export class App {
oidc = inject(Oidc);
// Use a getter so we read issuerUri only after init
get keycloakUtils() {
return createKeycloakUtils({ issuerUri: this.oidc.issuerUri });
}
// Example: drive an "Admin only" link state
get canShowAdminLink(): boolean {
if (!this.oidc.isUserLoggedIn) return true;
const roles = this.oidc.$decodedIdToken().realm_access?.roles ?? [];
return roles.includes('admin');
}
}
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import Header from "@/components/Header";
import { AutoLogoutWarningOverlay } from "@/components/AutoLogoutWarningOverlay";
import appCss from "../styles.css?url";
import { useOidc } from "@/oidc";
export const Route = createRootRoute({
head: () => ({ /* ... */ }),
shellComponent: RootDocument
});
function RootDocument({ children }: { children: React.ReactNode }) {
const { isOidcReady } = useOidc();
return (
<html lang="en">
<head>
<HeadContent />
</head>
<body
className="min-h-screen text-white"
style={{
backgroundColor: "#0f172a",
backgroundImage: "linear-gradient(180deg, #0f172a 0%, #1e293b 50%, #0f172a 100%)"
}}
>
<div className="min-h-screen flex flex-col">
{isOidcReady && (
<>
<Header />
<main className="flex flex-1 flex-col">
<div className="flex flex-1 flex-col">{children}</div>
</main>
</>
)}
</div>
<AutoLogoutWarningOverlay />
<Scripts />
</body>
</html>
);
}
{isUserLoggedIn ?
);
}
function Greeting() {
- const { isOidcReady, isUserLoggedIn, decodedIdToken } = useOidc();
+ const { isOidcReady, isUserLoggedIn, decodedIdToken } = useOidc({ assert: "ready" });
- if (!isOidcReady) {
- return <> ;
- }
return (
{isUserLoggedIn ? `Welcome back ${decodedIdToken.name}` : `Hello anonymous visitor!`}
);
}
```
{% endtab %}
{% endtabs %}
# Talking to multiple APIs (with different access tokens)
{% hint style="info" %}
TL;DR
Most apps only need one access token for their backend API.
The rest of this page explains how to talk to multiple APIs securely (Keycloak-style) using oidc-spa.
{% endhint %}
With **oidc-spa**, your **frontend application is the OIDC client**. Your **backend** is **only** a resource server that you call by attaching an `Authorization: Bearer -
{Object.entries(userSecrets).map(([key, value]) => (
- {key}
- {value}
{(()=>{ switch(backFromAuthServer.result.kc_action_status){ case "success": return "Password successfully updated"; case "cancelled": return "Password unchanged"; } })()}
)} ); } ``` {% endtab %} {% tab title="Angular" %} ```typescript updatePassword = ()=> this.oidc.goToAuthServer({ extraQueryParams: { kc_action: "UPDATE_PASSWORD" } }); ``` ```angular-html @if( oidc.backFromAuthServer?.extraQueryParams.kc_action === "UPDATE_PASSWORD" ){ @if ( oidc.backFromAuthServer.result.kc_action_status === "success" ){Password successfully updated
} @else {Password unchanged
} } ``` {% endtab %} {% endtabs %} # Keycloak Utils oidc-spa is provider agnostic.\ You won’t find any Keycloak-only logic in the core package. If you *are* using Keycloak, `oidc-spa/keycloak` exposes small utilities to leverage Keycloak-specific URLs and endpoints. {% hint style="info" %} These utilities are **pure** (no side effects) and only need your `issuerUri`.\ `createKeycloakUtils()` is memoized, so it’s safe to call often. {% endhint %} ### Import ```typescript import { createKeycloakUtils, isKeycloak } from "oidc-spa/keycloak"; ``` ### Optional runtime check: is this issuer Keycloak? Useful when your app can run against multiple providers. ```typescript const oidc = await getOidc(); // or useOidc() or inject(Oidc) if (!isKeycloak({ issuerUri: oidc.issuerUri })) { console.log("The authorization server is not a Keycloak instance"); return; } ``` ### Create the utils object ```typescript const keycloakUtils = createKeycloakUtils({ issuerUri: oidc.issuerUri }); ``` ### Common use cases #### Redirect to the registration page (instead of login) ```typescript oidc.login({ doesCurrentHrefRequiresAuth: false, transformUrlBeforeRedirect: keycloakUtils.transformUrlBeforeRedirectForRegister }); ``` #### Link to the Keycloak Account Console Users can update their profile, password, MFA, sessions, etc. ```typescript const accountUrl = keycloakUtils.getAccountUrl({ clientId: oidc.clientId, validRedirectUri: oidc.validRedirectUri, locale: "en" // Optional }); ``` See: [User Account Management](/v9/features/user-account-management#redirecting-to-your-idps-account-managment-page) #### Fetch the Keycloak user profile (Keycloak-internal endpoint) This is richer than the decoded ID token.\ Equivalent of `keycloak-js` `.loadUserProfile()`. ```typescript const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken const userProfile = await keycloakUtils.fetchUserProfile({ accessToken }); userProfile.id; userProfile.username; userProfile.attributes; ``` #### Fetch user info (OIDC `userinfo` endpoint) Equivalent of `keycloak-js` `.loadUserInfo()`. ```typescript const accessToken = await oidc.getAccessToken(); // or (await oidc.getTokens()).accessToken const userInfo = await keycloakUtils.fetchUserInfo({ accessToken }); userInfo.sub; ``` The userInfo object is similarly shaped as what you get if you decode the payload of the access token (which you shouldn't do on the client, see: [JWT Of the Access Token](/v9/resources/jwt-of-the-access-token)) ```typescript import { decodeJwt } from "oidc-spa/decode-jwt"; const decodedAccessToken = decodeJwt(accessToken); ``` #### Admin Console URLs Only show these links to privileged users (for example `realm-admin`). ```typescript keycloakUtils.adminConsoleUrl; // Admin console for the current realm keycloakUtils.adminConsoleUrl_master; // Admin console for the "master" realm ``` ### Parse the issuer URI ```typescript const { issuerUriParsed } = keycloakUtils; // Example issuerUri: // "https://auth.my-company.com/realms/myrealm" issuerUriParsed.origin; // "https://auth.my-company.com" issuerUriParsed.realm; // "myrealm" issuerUriParsed.kcHttpRelativePath; // undefined or "/auth" if the issuer uri was "https://auth.my-company.com/auth/realms/myrealm" ``` # Overview How oidc-spa mitigates the risks of token exposure oidc-spa implements a comprehensive, defense-in-depth strategy to protect against token exfiltration during a successful XSS or supply-chain attack. ## Enabling the defences With oidc-spa, all current best practices are implemented out of the box: * **No persistence**: tokens live in memory only. Sessions are restored by contacting the Authorization server on every app reload. * PKCE is always required and can't be disabled. * Single, non-dynamic [valid redirect URI](#user-content-fn-1)[^1]. (As opposed to keycloak-js, which requires configuring a redirect URI with a wildcard, like| /pages/OQPfLaz21wcSz22qMpf2 |
| /pages/AkX224WAW7UAYAoUymBd |
| /pages/zmd4gn3akUmtOPPYQAXq |