Another big difference: oidc-spa is browser-centric. The token exchange happens on the client, and the backend server is merely an OAuth2 resource server in the OIDC model.

If you use BetterAuth to provide login via Keycloak, your backend becomes the OIDC client application, which has some security benefits over browser token exchange, but at the cost of centralization and requiring backend infrastructure.

One clear advantage BetterAuth has over oidc-spa is more natural SSR support. In the oidc-spa model, the server doesn’t know the authentication state of the user at all time, which makes it difficult to integrate with traditional full-stack frameworks that rely on server-side rendering.

Server Side Rendering

The only SSR-capable framework we currently support is TanStack Start, because it provides the low-level primitives needed to render as much as possible on the server while deferring rendering of auth aware components to the client.

This approach achieves a similar UX and performance to server-centric frameworks, but it’s inherently less transparent than streaming fully authenticated components to the client.

Try the TansStack Start example deployment with JavaScript disabled to get a feel of what can and can't be SSR'd: https://example-tanstack-start.oidc-spa.dev/

Security and XSS resilience

Yes; client-side authentication raises valid security concerns. But this isn’t a fatal flaw; it’s an engineering challenge, and oidc-spa addresses it head-on.

It treats the browser as a hostile environment, going to great lengths to protect tokens even under XSS or supply-chain attacks. These mitigations are documented here.

Limitations regarding backend delegation

The main limitation is with long-running background operations. If your backend must call third-party APIs on behalf of the user while they’re offline, you’ll need service accounts for those APIs or take charge of rotating tokens yourself which can be tricky. Beyond that, everything else scalability, DX, performance, works in your favor.

If that all sounds good to you… Let’s get started.

In that case, follow the React Router integration guide in Declarative Mode, it should be easy to adapt to your setup.

Installation

To protect tokens against supply-chain attacks and XSS, oidc-spa must run some initialization code before any other JavaScript in your app.

This design provides much stronger security guarantees than any other adapter, and it also delivers unmatched login performance. More details here.

Basic Usage

Mock Adapter

For certain use cases, you may want a mock adapter to simulate user authentication without involving an actual authentication server.

This approach is useful when building an app where user authentication is a feature but not a requirement. It also proves beneficial for running tests or in Storybook environments.

Creating an API server

Now that authentication is handled, there’s 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’re 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’ll find the full documentation here:

Once enabled, make sure to check "Preserve Log" in your browser’s console options so the logs aren’t cleared during redirects.

Here’s a common example: If you see a message like this in the console, it usually means your Valid Redirect URIs list in your IdP configuration is incomplete:

In this case, simply add http://localhost:3000/ (or the appropriate URL for your environment) to your list of valid redirect URIs in the IdP settings.

Gracefully Handling Errors in Production

Learning from the example

You're going to be cloning this example:

React Router v7 has three modes pick the one for you:

Creating an API server

Now that authentication is handled, there’s 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’re 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’ll find the full documentation here:

• Authorization Code Flow: Requires a backend to perform the token exchange, since a client secret is needed to securely obtain tokens. In this model, the server acts as the OIDC client application. Frameworks like NextAuth follow this approach. The resulting access token is mostly incidental, it's used only if we need to call third party APIs.

• Authorization Code Flow with PKCE: Adds an additional verification step that removes the need for a client secret, enabling secure token exchange directly from the browser. This is the flow implemented by oidc-spa. Here, the frontend itself is the OIDC client application, and the access token is used as a key to make authenticated requests to a backend that otherwise has no built-in knowledge of authentication.

1. Authorization Code Flow (without PKCE)

This flow is typically implemented as follows:

1. The frontend initiates authentication but does not exchange the authorization code directly.

2. Instead, the backend receives the authorization code and uses a client secret to exchange it for tokens.

3. The backend stores the access and refresh tokens in a database.

4. The backend issues an HttpOnly session cookie to the frontend.

5. The frontend communicates with the backend, which retrieves and attaches access tokens to API requests using the session identifier stored in the cookie.

2. Authorization Code Flow + PKCE (Used by oidc-spa)

The standard Authorization Code Flow alone is insufficient for securely exchanging tokens directly from the browser, as it requires a client secret. Since anything embedded in frontend code is not truly secret, a different approach is needed.

This is where PKCE (Proof Key for Code Exchange) comes in. Here’s how it works with oidc-spa:

1. When the user needs to log in, either by clicking a "Login" button or by navigating to a protected part of the app, oidc-spa redirects them to the OIDC provider's login page (e.g., Keycloak, Auth0).

2. After successful authentication, the OIDC provider establishes a session, sets an HttpOnly session cookie in the browser, and redirects the user back to the app with an authorization code.

3. oidc-spa exchanges this code for tokens, completing a cryptographic challenge that eliminates the need for a client secret.

4. Tokens remain in memory only, oidc-spa does not store them in localStorage, sessionStorage, or a backend database.

5. When the user refreshes the page or revisits the app, oidc-spa restores the session by querying the OIDC provider in the background.

6. The OIDC provider uses the session cookie to determine whether the session is still valid. If it is, fresh tokens are issued without requiring the user to log in again.

7. If the session has expired, the user is redirected to the login page when accessing a protected area.

Note: You might be concerned about the use of cookies, but here we are referring to session cookies, which do not require GDPR consent and are always enabled in all browsers. A user who disables all cookies would not be able to use any website requiring authentication. Session cookies should not be confused with tracking cookies or third-party cookies.

Advantages and Trade-offs of Implementing Token Exchange on the Frontend

✅ No persistent token storage – There’s no need to store user tokens in a backend database. The OIDC provider itself acts as the session store, meaning you only need to focus on securely deploying your OIDC server (if self-hosting).

✅ Fewer moving parts – Everything happens between oidc-spa and the OIDC provider, reducing the chances of misconfiguration. Even if you're not entirely confident in your setup, as long as it works, you’ve implemented it correctly.

However, in this mode, tokens are exposed to the JavaScript client code, unlike when the token exchange is performed on the backend. This introduces a potential risk: XSS and supply chain attacks, where malicious code running on your website could attempt to steal tokens.

How oidc-spa Mitigates the Risks of Token Exposure

Opinionated Conclusion

PKCE is a widely adopted open standard, supported by all major OIDC providers, and provides strong security guarantees without requiring a backend.

While a backend-based token exchange is theoretically more secure, in practice, it introduces additional attack surfaces and operational complexity. Every extra moving part is a potential point of failure or misconfiguration, and securing a backend against threats like token leakage, improper session management, and server-side vulnerabilities is a non-trivial task.

With the security measures implemented in oidc-spa, Authorization Code Flow + PKCE is not just the simpler approach, it is arguably the safer one in real-world scenarios. By eliminating the backend entirely, it reduces the risk of misconfiguration and ensures that authentication security is handled directly by the OIDC provider, which is purpose-built for this task.

Read more:

1) Your app cannot iframe the IdP

This happens when:

• X-Frame-Options: DENY

• Content-Security-Policy: frame-src 'none'

• Content-Security-Policy: frame-src 'self'

• Content-Security-Policy: frame-src 'self' https://not-my-idp.com

If the IdP domain is missing from frame-src, the iframe cannot load → silent SSO cannot run.

2) Your app cannot be iframed by itself

Silent SSO needs to temporarily load your app inside an iframe (when the IdP redirects back with the authorization response).

If you block this:

• Content-Security-Policy: frame-ancestors 'none'

…then the IdP cannot redirect to your app inside the iframe → silent SSO fails.

How to fix it

To restore silent SSO:

1. Remove any X-Frame-Options header (deprecated).

2. Allow the IdP domain in frame-src.

3. Allow your app to frame itself using frame-ancestors 'self'.

Example:

Tip: Instead of hardcoding the IdP domain, allow sibling subdomains of your app’s domain. This stays aligned with same-site cookie rules and avoids config drift between environments.

The Nginx configuration below demonstrates this pattern.

Canonical Nginx configuration

This is a portable, production-grade Ngnix config for an SPA with "as strict as can be" CSPs that still enable oidc-spa to use iframe for performing session restoration.

Of course you can relax thoses CSP to meet the specific need of your app. This is just an example of what you would use if you use no service/web workers and don't have any inline script.

2. Add required scripts to your HTML head

Edit your public.html (or the file that defines your HTML head, e.g. in TanStack Start or React Router framework mode) and add the following scripts:

3. Import the shim

✅ Summary: If you see the error Crypto.subtle is available only in secure contexts (HTTPS) in a non-HTTPS environment, install webcrypto-liner. This allows oidc-spa to work even on local or intranet setups without HTTPS.

Well there is a way to go around this, and that is to ask oidc-spa to substitute the Acess Token by the ID token.

Be aware that this is a hack, the ID token is not meant to be sent to the API but it works.

This is unnecessary. You don’t need a valid access token cached at all times.

The Correct Approach (What oidc-spa Does)

Whenever you need to make an authenticated request, just ask oidc-spa for a token:

• If a valid token is cached, you’ll get it.

• If it’s expired, oidc-spa silently refreshes it using the refresh token.

So the correct approaches when you need an access token are:

• via an interceptor that injects it into requests, or

• with a wrapper around fetch() that awaits oidc.getAccessToken().

Example: interceptor pattern Example: custom fetch

Behind the scenes, oidc-spa ensures the session never expires prematurely by refreshing at least once before the refresh token itself expires. This prevents the backend from destroying the session simply because the user wasn’t making authenticated requests (e.g., they’re filling out a form or browsing content).

At the same time, oidc-spa tracks actual user activity (keyboard, mouse, touch). If the user is truly idle beyond the refresh token lifespan, they’re logged out as expected.

This is the only correct model. There aren’t “multiple valid strategies.” It shouldn’t be configurable, because there is nothing to configure.

Why Other Adapters Get It Wrong

Adapters like keycloak-js expose the access token synchronously (keycloak.token). To keep that contract, they’re forced to brute-force the server with background refreshes, otherwise, you might read an expired token.

That’s why they give you knobs to “configure auto-renewal.” In reality, this pushes responsibility onto you for something the adapter should handle internally.

On top of that the fresh loop does not even guarenty you'll never read an expired token, for example, when the computer wakes up from sleep to an expired token, the token can be expired and the adapter would have had no time to refresh it. The Keycloak team is well aware of the design flaw of keycloak-js and keep it as is because changing the API would cause too much distruption. However, when they use keycloak-js internally for their app, like the Admin Console. They apply the same strategy as oidc-spa.

Why oidc-spa Still Exposes renewTokens()

There are two legitimate edge cases:

1. After custom requests: If you make a request to your OIDC server that changes claims in the id_token or access_token, call renewTokens() to ensure you have the latest values. (This is a very rare usecase, usually the user info are updated outside of your app, if you're not sure, you can safely assume your not doing any of those request).

2. Custom token parameters: If your OIDC server supports extra token endpoint params, you can trigger a refresh with them. (extraTokenParams is also available at createOidc() time.)

Outside of these rare cases, you never need to call renewTokens() manually.

👉 With oidc-spa, token renewal is always correct, efficient, and invisible to you.

Enabling the defence is simply a matter of flipping a switch:

⸻

Understanding the Security Guarantees (and Their Limits)

Supply-Chain Attacks

If an NPM dependency is compromised, the damage remains extremely limited:

• The attacker cannot exfiltrate valid tokens

• This blocks the most common and impactful class of supply-chain attacks • Most real-world supply-chain malware is opportunistic, not targeted

An attacker could theoretically act on behalf of the user during the active compromise, but:

• This requires a targeted attack specifically against your build

• This is realistic only for massive, high-value open-source systems

• Even then, oidc-spa makes it very difficult

Why? Because unlike session-cookie auth, where any fetch() automatically includes credentials, here the attacker must obtain a reference to your fetchWithAuth() or getOidc() functions.

These functions usually live inside hashed static assets (example: assets/KcAdminUi-BV3D797K.js). The hash will likely differ between the moment the attacker crafts the exploit and the moment the compromised dependency lands in your build.

Additionally, oidc-spa blocks the discovery of the module graph[^1].

Bottom line: For supply-chain attacks, oidc-spa offers stronger protection than traditional session cookies.

⸻

XSS Attacks

XSS remains dangerous. oidc-spa protects agaist token exfiltration, but an attacker who would know everything about your build can still manage to act on behafe of user while the attack is going on.

They can import your fetchWithAuth() implementation (exposed somwere ine the hashed js assets) and perform any action the current user is allowed to perform

The good news is that XSS can be very effectively blocked with strict Content-Security-Policy (CSP). And you should absolutely enable one.

⸻

Compromised Browser Extensions

This is the one scenario where cookie-based auth has an advantage over oidc-spa's client side auth.

If a user installs a malicious browser extension, it can inspect outgoing network traffic and see the substituted tokens.

This affects only the user with the compromised extension, and it affects all SPAs using client-side auth, not just your app.

⸻

How oidc-spa Achieves This

The entire strategy relies on the fact that, thanks to the Vite plugin or oidcSpaEarlyInit, oidc-spa gets a guaranteed window of execution before any other JavaScript runs.

During that window, it can:

• Harden the environment by preventing monkey-patching of fetch, XHR, WebSocket, Promise, String, and other critical built-ins

• Safely extract the authorization response from the URL and store it in memory

• Register a message listener that cannot be unregistered, ensuring silent-signin integrity • Enforce restrictions on service worker registration

• And most importantly:

Tokens are never exposed to the application layer

The tokens your app sees are structurally valid JWTs, but the signature segment is replaced. Such tokens cannot be used to authenticate requests.

Before any request leaves the app (fetch, XHR, WebSocket, beacon), the real tokens are restored inside a hardened, sandboxed pre-network interceptor created during early init.

The only way to see the real token is to inspect network traffic.

These protections have zero impact on DX or performance. The only requirement is to avoid libraries that monkey-patch critical built-ins and know ahead of time which resources server outside of your site your app might want to send authed request to (like s3.amazon.com for example).

1. Go to Microsoft Azure Portal.

2. In the left panel, select "Microsoft Entra ID".

3. Navigate to "Manage > App Registrations".

4. Click "New Registration".

5. Enter "My App - API" as the name, then click Register.

6. Set Supported Account Type to Accounts in this organization.

7. In the left menu, go to "Manage > Expose API".

8. Click "Add a scope".

9. Configure as follows, then click "Add Scope":

   • Application ID URI: api://my-app-api (then save and continue)

   • Scope name: access_as_user

Validating the Token on the Backend

To validate the token on the backend, ensure that the aud claim in the JWT access token matches api://my-app-api. For more details, refer to the Web API documentation.

Registering Your Application

1. Go to Microsoft Azure Portal.

2. In the left panel, select "Microsoft Entra ID".

3. Navigate to "Manage > App Registrations".

4. Click "New Registration".

5. Enter "My App" as the display name (replace with your actual app name).

6. Set Supported Account Type to Accounts in this organization.

7. Click Register.

8. Click "Add a Redirect URI".

9. Click "Add Platform" > "Single-Page Application".

10. Set Redirect URIs:

    • Production: https://my-app.com/ (include trailing slash; adjust if hosted under a subpath, e.g., https://my-app.com/dashboard/)

    • Local Development: http://localhost:5173/ (include trailing slash; adjust based on your dev server)

11. Ensure "Access Token" and "ID Token" are checked.

12. Click Save.

13. In the left panel, go to "API Permissions".

14. Click "Add a permission".

15. Click "APIs My Organization Uses".

16. Select "My App - API".

17. Check "access_as_user", then click "Add permission".

18. In the left panel, click "Overview" and copy:

    • Application (client) ID

    • Directory (tenant) ID

These are required to configure oidc-spa.

Configuring oidc-spa

Testing the Setup

To test your configuration:

Do your security headers allow self‑iframes?

• Yes → You are set.

• No → Either relax to frame-ancestors 'self' or stick to "full page redirect".

But if your app has no public pages, all of this can be simplified. Auto Login lets you assume the user is always logged in, and that every page implicitly requires authentication.

The great thing about JWT validation is that it works offline, there’s no need to contact your authorization server every time to ask “Is this token valid and issued by you?”

oidc-spa (server) simply fetches the public key published by your IdP once, then uses it to verify that each incoming token: • was signed by the IdP, • targets the expected audience, and • hasn’t expired.

This is a huge advantage for edge runtimes, since identity and authorization can be established locally no external round trips before executing user-specific logic.

To authorize certain routes or actions, you can perform additional checks on claims like groups or realm_access.roles.

And because access tokens issued through the Authorization Code Flow + PKCE are short-lived (typically 5 minutes or less), decoupling session lifetime from token validity isn’t an issue in practice.

Example with Express and Hono

Let’s say we have a Node.js REST API built with Express or Hono. We’ll create a function that takes an access token (and optionally a required role) and performs the following checks:

• ✅ Validates that the token was issued by the expected IdP.

• ✅ Ensures the token is still valid (not expired or tampered with).

• ✅ Confirms the audience matches this specific API — meaning the token was minted for it.

• ✅ Checks that the user has the required role, if one is specified.

If any of these conditions fail, we throw a specialized Hono error, which will cause the HTTP response to return 401 Unauthorized.

If the token passes all checks, the function returns the user’s ID (sub claim), allowing the rest of your API logic to identify who made the request.

Let's create a oidc.ts file:

Then you can enforce that some endpoints of your API requires the user to be authenticated, in this example we use Hono:

Testable example

This is a kitchen think example with the following stack:

• Vite

• TanStack Router - File Based Routing

• A Todos Rest API implemented with Node and Hono

The app is live here:

The frontend (Vite project):

The backend Node Todos App REST API with Express and Hono:

In frontend-centric apps, you often need to call several APIs (resource servers), for example:

• Your own REST API

• Amazon S3

• HashiCorp Vault

• …

You can proxy those calls through your backend using a service account. That is a valid approach, but many architectures prefer to keep the backend light and stateless, and to concentrate logic in the frontend to lower infra cost and improve responsiveness.

The challenge is that you should not reuse a single access token across different APIs. Even if it “works,” it is a poor security posture and will usually fail in practice because claims differ per API.

Why a single token is not enough

Access tokens carry claims that describe who the user is, who the token is for, and what permissions it grants.

Example:

• aud (audience) identifies the intended resource server.

• sub is the user identifier.

• Other claims (such as groups, scope, or custom claims) express authorization details.

Most OAuth-protected APIs require a specific audience and expect claims to be formatted in a particular way. These expectations often differ between APIs.

The right approach

Do not send the same access token to every resource server. Instead, configure your IdP so the client can obtain distinct access tokens for each target API, each token crafted exactly as that API expects.

Ideal world: Resource Indicators (RFC 8707)

In the ideal case, oidc-spa would support:

Your IdP would let you declare APIs independently and authorize which OIDC clients can request tokens for each API. Some providers like Auth0 or Microsoft EntraID support this pattern but keycloak do not and since it's the de facto standard OpenID Connect server, we intentionally align with Keycloak’s capabilities. We therefore do not support features that Keycloak does not support as of today. This avoids exposing APIs that would not work for most deployments.

Today with Keycloak

Keycloak does not yet implement RFC 8707. In Keycloak’s interpretation, when you declare an OIDC client you effectively couple an application with a resource server. To talk to multiple resource servers, you declare multiple clients in the same realm, all sharing your app’s Valid Redirect URI.

Example:

• clientId: "myapp", valid redirect URI: https://myapp.my-company.com/

• clientId: "myapp-vault", valid redirect URI: https://myapp.my-company.com/

• clientId: "myapp-s3", valid redirect URI: https://myapp.my-company.com/

For each client, configure protocol mappers so the issued access token matches the target API’s expectations.

This limitation means that even if your IdP (Auth0, Clerk...) supports declaring APIs independently, you will still set things up this way to work with oidc-spa today.

Using multiple clients in oidc-spa

Once your clients exist, instantiate them side by side. oidc-spa fully supports multi-client usage.

Below is an example “My Secrets” page that exchanges an OIDC access token for a Vault token and then fetches the caller’s secrets. The example uses React, but the important parts use oidc-spa/core, so you can adapt it to your framework of choice.

That is all you need for multi-API access with per-API tokens.

Development and security caveats

The first time you call createOidc() you may get a full page redirect if silent session restoration via iframe is not available. This is the default on localhost in oidc-spa.

Also note that, if you configure more than one client AND iframe session restoration is not possible, oidc-spa will persist tokens in sessionStorage to avoid redirect loops. This relaxes the default security guarantees.

To remediate:

• (For production) Put your IdP authorization endpoint on the same parent domain as your app whenever possible.

• For a better dev experience allow third-party cookies in your local server and explicitely set sessionRestorationMethod: "iframe", by default it's set to "auto" mening that it will only use iframe if it knows that cookies won't be blocked, and oidc-spa can't know that in localhost.

More info and detailed instructions:

In Keycloak, the OIDC issuer URI follows this format:

https://<KC_DOMAIN><KC_RELATIVE_PATH>/realms/<REALM_NAME>

• <KC_DOMAIN>: The domain where your Keycloak server is hosted (e.g., auth.my-company.com).

• <KC_RELATIVE_PATH>: The subpath under which Keycloak is hosted. In recent versions, this is an empty string (""). In older versions, it was "/auth". Check your Keycloak server configuration; this parameter is typically set using an environment variable: Example: -e KC_HTTP_RELATIVE_PATH=/auth

• <REALM_NAME>: The name of your realm (e.g., myrealm). 🔹 Important: Always create a dedicated realm for your organization—never use the master realm. To create a new realm:

  1. Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.

  2. Log in as an administrator.

  3. Click on the realm selector in the top-left corner.

  4. Click "Create a new Realm"

clientId

The clientId is usually something like 'myapp'. Follow these steps to create a suitable client for your SPA:

1. Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.

2. Log in as an administrator.

3. Select your realm from the top-left dropdown.

4. In the left panel, click Clients.

5. Click Create Client.

6. Enter a Client ID, for example, myapp, and click Next.

7. Ensure Client Authentication is off, and Standard Flow is enabled. Click Next.

8. Set two Valid Redirect URIs, ensure both URLs end with /:

   • https://<APP_DOMAIN><BASE_URL>

   • http://localhost:<DEV_PORT><BASE_URL>
9. Click Save, and you're done! 🎉

Session Lifespan Configuration

One important policy to define is how often users need to re-authenticate when visiting your site.

🔐 Security-Sensitive Apps (Banking, Admin Panels, etc.)

For security-critical apps, users should log in each visit and be logged out after inactivity.

Why? Users accessing sensitive applications should not remain authenticated indefinitely, especially if they step away from their device. The session idle timeout ensures automatic logout after inactivity.

Steps to enforce this policy:

1. Disable "Remember Me":

   • Select your realm.

   • Navigate to Realm Settings → Login.

   • Set "Remember Me" to Off.

2. Configure session timeout:

   • Go to Realm Settings → Sessions.

   • Set SSO Session idle: 5 minutes (ensures users are logged out after 5 minutes of inactivity).

3. Optionally, display a logout countdown before automatic logout:

🛍️ Non-Sensitive Apps (E-commerce, Social Media, etc.)

For apps where users should remain logged in for weeks or months (e.g., YouTube-style behavior):

1. Enable "Remember Me":

   • Select your realm.

   • Navigate to Realm Settings → Login.

   • Set "Remember Me" to On.

2. Configure session timeout:

   • Users without "Remember Me" will need to log in every 2 weeks:

     • Set Session idle timeout: 14 days.

🗑️ Allowing Users to Delete Their Own Accounts

By default, Keycloak does not allow users to delete their accounts.

If you implement a delete account button, users will see an "Action not permitted" error.

Enabling Account Deletion:

1. Navigate to Authentication → Required Actions.

2. Enable "Delete Account".

3. Go to Realm Settings → User Registration → Default Roles.

4. Click Assign Role, filter by client, select Delete Account, and assign it.

Testing the Setup

To test your configuration:

You can customize this behavior (toast, inline banner, maintenance page, retry, etc.) or surface an error page if that fits your UX.