\n \n
![](\"https://github.com/keycloakify/oidc-spa/actions/workflows/ci.yaml/badge.svg?branch=main\"){kind=icon}
\n \n \n ![](\"https://img.shields.io/npm/dw/oidc-spa\")
\n \n \n ![](\"https://img.shields.io/npm/l/oidc-spa\")
\n \n\n
\n \n \n \n \n \n \n \n
\n We're here to help!
\n \n \n \n
\n Home\n -\n Documentation\n
\n\noidc-spa is an OpenID Connect client built for browser-first apps. \nIt wraps the full Authorization Code + PKCE flow in a high-level API so you can ship secure app auth without stitching together multiple SDKs and ad-hoc glue.\n\n- 🔒 Security-first defaults: in-memory tokens, strict redirect handling, and opt-in defenses like [DPoP](https://docs.oidc-spa.dev/v/v10/security-features/dpop)\n and [token substitution](https://docs.oidc-spa.dev/docs/v9/security-features/token-substitution) to reduce token exposure risk.\n- 🧠Battle-tested auth UX: token renewal, idle timeout, auto login/logout, multi-tab session sync, and reliable session restore on reload.\n- 🧩 Full-stack ready: [backend token validation utilities](https://docs.oidc-spa.dev/v/v10/integration-guides/backend-token-validation) and [first-class TanStack Start integration](https://docs.oidc-spa.dev/v/v10/integration-guides/tanstack-router-start/tanstack-start) in the same library.\n- 🧰 Provider-aware: handles real-world quirks across Keycloak, Entra ID, Auth0, Google, and more.\n- ✨ Developer experience: types flow from config into the API, minimal knobs, and easy-to-mock auth for tests.\n\n[Get Started](https://docs.oidc-spa.dev)\n\n## At a glance\n\nThe Framework-Agnostic Adapter:\n\n```ts\nimport { createOidc, oidcEarlyInit } from \"oidc-spa/core\"; // ~33 KB min+gzip (See: https://docs.oidc-spa.dev/resources/bundle-size)\nimport { z } from \"zod\"; // 59 KB min+gzip, but it's optional.\n\n// Call this only if you don't use oidc-spa's Vite plugin.\noidcEarlyInit({ BASE_URL: \"/\" });\n\nconst oidc = await createOidc({\n issuerUri: \"https://auth.my-domain.net/realms/myrealm\",\n //issuerUri: \"https://login.microsoftonline.com/...\",\n //issuerUri: \"https://xxx.us.auth0.com/...\"\n //issuerUri: \"https://accounts.google.com/o/oauth2/v2/auth\"\n clientId: \"myclient\",\n // Optional; you can write a validator by hand, or give up some type-safety, your call.\n decodedIdTokenSchema: z.object({\n name: z.string(),\n picture: z.string().optional(),\n email: z.string(),\n realm_access: z.object({ roles: z.array(z.string()) })\n })\n // Yes, really, it's that simple; there are no other parameters to provide.\n // The Redirect URI (callback URL) is the root URL of your app (no public/callback.html involved).\n});\n\n// In oidc-spa the user is either logged in or they aren't.\n// The state will never mutate without a full app reload.\n// This makes reasoning about auth much, much easier.\nif (!oidc.isUserLoggedIn) {\n await oidc.login();\n // Never here\n return;\n}\n\nconst { name, realm_access } = oidc.getDecodedIdToken();\n\nconsole.log(`Hello ${name}`);\n\nconst { accessToken } = await oidc.getTokens();\n\nawait fetch(\"https://my-domain.net/api/todos\", {\n headers: {\n Authorization: `Bearer ${accessToken}`\n }\n});\n\nif (realm_access.roles.includes(\"realm-admin\")) {\n // User is an admin\n}\n```\n\nHigher-level adapters, example with React but we also feature a similar Angular adapter:\n\n\n Keycloak as a Service — Keycloak community contributors of popular extensions providing free and dedicated Keycloak hosting and enterprise Keycloak support to businesses of all sizes.\n
\n","readmeFilename":"README.md"}