v8 -> v10

Since v9 and v10 where released within a short interval here is a guide to upgrade directly from v8 to v10.

Renames

These are pure renames. A simple search/replace is enough:

- import { ... } from "oidc-spa";
+ import { ... } from "oidc-spa/core";

- import { ... } from "oidc-spa/mock";
+ import { ... } from "oidc-spa/core-mock";

- import { ... } from "oidc-spa/tools/decodeJwt";
+ import { ... } from "oidc-spa/decode-jwt";

- oidc.params.issuerUri;
+ oidc.issuerUri;

- oidc.params.clientId;
+ oidc.clientId;

- oidc.params.validRedirectUri;
+ oidc.validRedirectUri;

- const { unusbscribe } = oidc.subscribeToTokensChange(...);
+ const { unsubscribeFromTokensChange } = oidc.subscribeToTokensChange(...);

createOidc({
-    noIframe: true
+    sessionRestorationMethod: "full page redirect"
});

homeUrl removed

 createOidc({ // createMockOidc({
-    homeUrl: import.meta.env.BASE_URL,
});

Vite Plugin

That's it.

Manual

Vite Plugin and oidcEarlyInit Params changes

oidc-spa's security features have been reworked, see: Security Features

This is the changes you need to apply to migrate your current config while keeping the same security profile:

Vite Plugin

vite.config.ts

  oidcSpa({
-   enableTokenExfiltrationDefense: true,
-   resourceServersAllowedHostnames: ["s3.amazonaws.com"],
+   browserRuntimeFreeze: { enabled: true },
+   tokenSubstitution: {
+       enabled: true,
+       trustedExternalResourceServers: [
+           "*.{{location.hostname.split('.').slice(-2).join('.')}}",
+           "s3.amazonaws.com"
+       ]
+   }
});

If you’re migrating from the older freeze* flags:

vite.config.ts

 oidcSpa({
-    freezeFetch: false,
-    freezeXMLHttpRequest: false,
-    freezeWebSocket: true,
-    freezePromise: true
     // Add to `exclude` the APIs for which you had `freezeXxx: false`.
+    browserRuntimeFreeze: {
+        enabled: true,
+        excludes: ["fetch", "XMLHttpRequest"]
+    }
});

Manual

Update of keycloakUtils.getAccountUrl() API

The "back to app" url actually only allows to redirect to a valid redirect uri.

 const accountUrl = keycloakUtils.getAccountUrl({
     clientId: oidc.clientId,
-    backToAppFromAccountUrl: location.href,
+    validRedirectUri: oidc.validRedirectUri,
     locale: "en" // Optional
 });

Removal of oidc-spa/tools/parseKeycloakIssuerUri

There is now more comprehensive keycloak integration utils: Keycloak Utils

-import { parseKeycloakIssuerUri } from "oidc-spa/tools/parseKeycloakIssuerUri";

-const issuerUri = oidc.params.issuerUri;
-const clientId = oidc.params.clientId;

-const keycloak = parseKeycloakIssuerUri(issuerUri);

-if( keycloak === undefined ){
-    console.log("Not keycloak");
-    return;
-}

-const { origin, realm, kcHttpRelativePath, adminConsoleUrl, getAccountUrl } = keycloak;

-const accountUrl = getAccountUrl({
-    thisAppDisplayName: clientId,
-    backToAppFromAccountUrl: location.href
-});

+ import { createKeycloakUtils, isKeycloak } from "oidc-spa/keycloak";

+const issuerUri = oidc.issuerUri;
+const clientId = oidc.clientId;
+const validRedirectUri = oidc.validRedirectUri;

+if( !isKeycloak({ issuerUri }) ){
+    console.log("Not keycloak");
+    return;
+}

+const keycloakUtils = createKeycloakUtils({ issuerUri });

+const { origin, realm, kcHttpRelativePath } = keycloakUtils.issuerUriParsed;

+const { adminConsoleUrl } = keycloakUtils;

+const accountUrl = keycloakUtils.getAccountUrl({
+    clientId: oidc.clientId,
+    validRedirectUri: oidc.validRedirectUri,
+    locale: "en" // Optional
+});

React entrypoint rename (breaking)

Breaking change. oidc-spa/react has been removed. Use oidc-spa/react-spa.

The overall approach is the same, but the API changed significantly.

Use the new integration guide:

React SPA integration guide

Server entrypoint rename (breaking)

Breaking change. oidc-spa/backend has been removed. Use oidc-spa/server.

This was required to support DPoP. It also cleans up the API.

Use the new docs: Server integration guide

crypto.subtle polyfill

oidc-spa now auto-polyfills crypto.subtle when it’s missing (typically when not served over HTTPS). This has no bundle size impact.

If you previously added webcrypto-liner-shim as described here, you can remove it.

Need a hand?

If you hit a migration edge case, ask on Discord:

Discord invite