v8 -> v10.0.1-rc.x

This is the direct migration path from oidc-spa v8 to v10.

It’s basically v8 → v9 + v9 → v10, but written as a single flow.

1) Renames (v8 → v9)

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"
});

2) homeUrl removed (v8 → v9)

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

Vite Plugin

That’s it.

Manual

3) Security defenses config (v8 → v10)

In v9, security defenses were reworked. In v10, DPoP became global, and token-substitution options were renamed.

Vite plugin

From v8 config (enableTokenExfiltrationDefense / resourceServersAllowedHostnames)

vite.config.ts

oidcSpa({
-  enableTokenExfiltrationDefense: true,
-  resourceServersAllowedHostnames: ["s3.amazonaws.com"],
+  browserRuntimeFreeze: { enabled: true },
+  tokenSubstitution: {
+    enabled: true,
+    trustedExternalResourceServers: [
+      // Add your own wildcard if you want to trust "same site" subdomains.
+      "*.my-domain.com",
+      "s3.amazonaws.com"
+    ]
+  },
+  DPoP: { mode: "auto" /* or "enforced" */ }
});

From v8 config (older freeze* flags)

Manual (no Vite plugin)

From v8 config (enableTokenExfiltrationDefense / resourceServersAllowedHostnames)

src/main.ts

import { oidcEarlyInit } from "oidc-spa/entrypoint";
-import { enableTokenSubstitution } from "oidc-spa/token-substitution";
+import { browserRuntimeFreeze } from "oidc-spa/browser-runtime-freeze";
+import { DPoP } from "oidc-spa/DPoP";
+import { tokenSubstitution } from "oidc-spa/token-substitution";

const { shouldLoadApp } = oidcEarlyInit({
-  enableTokenExfiltrationDefense: true,
-  resourceServersAllowedHostnames: ["s3.amazonaws.com"],
+  securityDefenses: {
+    ...browserRuntimeFreeze({
+      // exclude: ["fetch", "XMLHttpRequest", "Promise"]
+    }),
+    ...DPoP({ mode: "auto" /* or "enforced" */ }),
+    ...tokenSubstitution({
+      trustedExternalResourceServers: [
+        "s3.amazonaws.com",
+        "*.my-domain.com"
+      ]
+    })
+  }
});

From v8 config (older freeze* flags)

Takeaways (v9 → v10)

• trustedThirdPartyResourceServers was renamed to trustedExternalResourceServers.

• Same-site wildcards (like *.my-domain.com) are not trusted by default anymore. Add them explicitly if you relied on that.

• DPoP is now configured globally via DPoP / DPoP: { ... }.

4) Remove per-client dpop option (v9 → v10)

If you previously had this:

createOidc({ // or bootstrapOidc({
  // ...
- dpop: "auto"
});

Remove it. DPoP is now configured globally (see above).

5) Update of keycloakUtils.getAccountUrl() API (v8 → v9)

The “back to app” URL now must be a valid redirect URI:

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

6) Removal of oidc-spa/tools/parseKeycloakIssuerUri (v8 → v9)

There are now Keycloak utilities:

-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,
+  validRedirectUri,
+  locale: "en" // Optional
+});

7) React entrypoint rename (breaking) (v8 → v9)

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

Use the new integration guide:

React SPA integration guide

8) Server entrypoint rename (breaking) (v8 → v9)

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

Use the new docs:

Server integration guide

9) crypto.subtle polyfill (v8 → v9)

oidc-spa now auto-polyfills crypto.subtle when it’s missing.

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

Need a hand?

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

Discord invite