Migrating from Keycloak-js

Polyfilling keycloak-js with oidc-spa

If you're using keycloak-js in an existing codebase, you can migrate to oidc-spa without a painful rewrite. oidc-spa ships a keycloak-js polyfill. It’s a literal drop-in replacement.

Why switch?

Security

Enabling DPoP: Keycloak, starting with 26.4, officially supports DPoP. keycloak-js doesn’t.
Browser Runtime Freeze
(Optional) 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. With oidc-spa, the only valid redirect URI is your app’s origin, for example https://dashboard.my-company.com/.

UX

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...)

Update dependency

Replace keycloak-js with oidc-spa in your package.json.

package.json

 {
     dependencies: {
-        "keycloak-js": "...",
+        "oidc-spa": "..."
     }
 }

Update your codebase

-import Keycloak from "keycloak-js";
+import { Keycloak } from "oidc-spa/keycloak-js";

 // ...

 await keycloak.init({
     onLoad: 'check-sso',
-    silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`,
     // ...
 });

Delete public/silent-check-sso.html.

(OPTIONAL) Fix your Valid Redirect URIs

Valid Redirect URIs:
 http://localhost*
-https://dashboard.my-company.com/*
-https://dashboard.my-company.com/silent-check-sso.html
+https://dashboard.my-company.com/

Enable Security Features

If you're moving to oidc-spa, you likely want to enable DPoP and other security features.

Pick the setup option that best fits your project:

If you're in a Vite project, the recommended approach is to use oidc-spa’s Vite plugin.

vite.config.ts

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
                //exclude: [ "fetch", "XMLHttpRequest"]
            },
            // See: https://docs.oidc-spa.dev/v/v10/security-features/dpop
            DPoP: {
                enabled: true,
                mode: "auto"
            }
        })
    ]
});

Pick this approach if:

You're not in a Vite project (or want more control) and
Your app has a single client entrypoint.

Let's assume your app entrypoint is src/main.ts.

First, rename it to src/main.lazy.ts.

mv src/main.ts src/main.lazy.ts

Then create a new src/main.ts file:

src/main.ts

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({
            //exclude: [ "fetch", "XMLHttpRequest" ]
        }),
        // See: https://docs.oidc-spa.dev/v/v10/security-features/dpop
        ...DPoP({ mode: 'auto' })
    }
});

If you’re not using Vite and you can’t edit your app’s entry file, run oidcEarlyInit() in the same module where you call new Keycloak().

Note: this option downgrades the security posture of your app compared to the two other approaches. It can also conflict with some client-side routing libraries.

src/oidc.ts

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({
            //exclude: [ "fetch", "XMLHttpRequest" ]
        }),
        // See: https://docs.oidc-spa.dev/v/v10/security-features/dpop
        ...DPoP({ mode: 'auto' })
    }
});

const keycloak = new Keycloak({ /* ... */ });

You can enable keycloak.init({ enableLogging: true }) to see a console report for the security features.

(OPTIONAL) Display a Warning Before Auto Logout

oidc-spa implements auto logout by respecting the idle session lifetime you configured in Keycloak.

To warn the user when they are about to be logged out due to inactivity, you can show an overlay like: “Are you still here? Your session will expire in 30…29…”

Get the underlying oidc-spa core object like this:

import { Keycloak } from "oidc-spa/keycloak-js";

const keycloak = new Keycloak({ ... });

await keycloak.init({ ... });

// Can call this only after keycloak.init() has resolved.
const oidc = keycloak.getOidc();

Then implement the overlay as described here: Displaying a Warning Before Auto Logout.

You're Done 🎉

If you run into some issue do not hesitate to reach out on Discord.

PreviousToken Substitution NextThird‑party cookies and session restoration

Last updated 1 day ago

Was this helpful?

hashtagSecurity

hashtagUX

hashtagUpdate dependency

hashtagUpdate your codebase

hashtag(OPTIONAL) Fix your Valid Redirect URIs

hashtagEnable Security Features

hashtag(OPTIONAL) Display a Warning Before Auto Logout

hashtagYou're Done 🎉