antaeus.keycloak.react 2.7.0 → 2.7.1

package/README.md

@@ -155,6 +155,27 @@ const { isEnabled, isConfigured, reason } = useKeycloakStatus();
 
 For mobile browsers and installed PWAs, token freshness is also checked when the app resumes from the background by default. Set `silentRenew.refreshOnResume` to `false` to disable this behavior.
 
+### Silent Renewal Fallback
+
+`oidc-client-ts` always uses a stored refresh token when one is available. To permit iframe renewal only when no refresh token is stored, opt in explicitly:
+
+```tsx
+<KeycloakProvider
+  authority="https://sso.example.com/realms/myrealm"
+  clientId="my-app"
+  config={{
+    silentRenew: {
+      allowIframeFallback: true,
+      transientRetry: { maxAttempts: 3, initialDelayMs: 1000, maxDelayMs: 30000 },
+    },
+  }}
+>
+  <App />
+</KeycloakProvider>
+```
+
+The application must host `silentRenew.silentRedirectUri` (default `/silent-renew.html`), register its exact URL with the identity provider, and allow the identity provider to load in an iframe. Browser privacy settings and third-party-cookie policy can still prevent iframe renewal. `useRefreshToken` remains for source compatibility but cannot force iframe-only renewal.
+
 ## React Hooks
 
 ### useAuth()

package/dist/index.d.mts

@@ -116,11 +116,23 @@ interface SilentRenewConfig {
      */
     loadingMessage?: string;
     /**
-     * Enable using the refresh token grant instead of iframe silent renew when available.
-     * Keeps long-lived sessions alive even after the app is closed.
+     * Legacy compatibility setting. oidc-client-ts automatically uses a stored
+     * refresh token when one is available.
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Allow oidc-client-ts to use iframe silent renewal when no refresh token is stored.
+     * The application must host the configured silentRedirectUri and permit it in the
+     * identity provider redirect URI allowlist.
+     * @default false
+     */
+    allowIframeFallback?: boolean;
+    /**
+     * Retry policy for transient online silent-renew failures.
+     * Offline renewals wait for the browser's online event instead of using this policy.
+     */
+    transientRetry?: TransientRetryConfig;
     /**
      * Re-check token freshness when a suspended tab/PWA resumes.
      * Useful for mobile browsers and installed PWAs where timers pause in the background.
@@ -128,6 +140,14 @@ interface SilentRenewConfig {
      */
     refreshOnResume?: boolean;
 }
+interface TransientRetryConfig {
+    /** Maximum automatic retries after a transient online failure. @default 3 */
+    maxAttempts?: number;
+    /** Delay before the first retry in milliseconds. @default 1000 */
+    initialDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. @default 30000 */
+    maxDelayMs?: number;
+}
 /**
  * Event callbacks for authentication lifecycle
  */

package/dist/index.d.ts

@@ -116,11 +116,23 @@ interface SilentRenewConfig {
      */
     loadingMessage?: string;
     /**
-     * Enable using the refresh token grant instead of iframe silent renew when available.
-     * Keeps long-lived sessions alive even after the app is closed.
+     * Legacy compatibility setting. oidc-client-ts automatically uses a stored
+     * refresh token when one is available.
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Allow oidc-client-ts to use iframe silent renewal when no refresh token is stored.
+     * The application must host the configured silentRedirectUri and permit it in the
+     * identity provider redirect URI allowlist.
+     * @default false
+     */
+    allowIframeFallback?: boolean;
+    /**
+     * Retry policy for transient online silent-renew failures.
+     * Offline renewals wait for the browser's online event instead of using this policy.
+     */
+    transientRetry?: TransientRetryConfig;
     /**
      * Re-check token freshness when a suspended tab/PWA resumes.
      * Useful for mobile browsers and installed PWAs where timers pause in the background.
@@ -128,6 +140,14 @@ interface SilentRenewConfig {
      */
     refreshOnResume?: boolean;
 }
+interface TransientRetryConfig {
+    /** Maximum automatic retries after a transient online failure. @default 3 */
+    maxAttempts?: number;
+    /** Delay before the first retry in milliseconds. @default 1000 */
+    initialDelayMs?: number;
+    /** Maximum exponential backoff delay in milliseconds. @default 30000 */
+    maxDelayMs?: number;
+}
 /**
  * Event callbacks for authentication lifecycle
  */

package/dist/index.js

@@ -37,6 +37,12 @@ var defaultConfig = {
     showLoadingIndicator: false,
     loadingMessage: "Refreshing session...",
     useRefreshToken: true,
+    allowIframeFallback: false,
+    transientRetry: {
+      maxAttempts: 3,
+      initialDelayMs: 1e3,
+      maxDelayMs: 3e4
+    },
     refreshOnResume: true
   },
   advanced: {
@@ -63,7 +69,6 @@ var KeycloakConfigBuilder = class {
     const config = this.mergeWithDefaults(userConfig);
     const storageType = config.advanced.storageType || "session";
     const storage = storageType === "local" ? window.localStorage : window.sessionStorage;
-    const { useRefreshToken } = config.silentRenew;
     const oidcSettings = {
       authority: config.authority,
       client_id: config.clientId,
@@ -81,9 +86,6 @@ var KeycloakConfigBuilder = class {
         response_mode: "query"
       }
     };
-    if (useRefreshToken !== void 0) {
-      oidcSettings.useRefreshToken = useRefreshToken;
-    }
     return oidcSettings;
   }
   /**
@@ -158,6 +160,9 @@ var useAuth = reactOidcContext.useAuth;
 
 // src/hooks/useTokenLifecycle.ts
 var STORAGE_KEY_PREFIX = "keycloak_first_login_";
+var DEFAULT_MAX_TRANSIENT_RETRIES = 3;
+var DEFAULT_RETRY_INITIAL_DELAY_MS = 1e3;
+var DEFAULT_RETRY_MAX_DELAY_MS = 3e4;
 var isNavigatorOffline = () => typeof navigator !== "undefined" && "onLine" in navigator && navigator.onLine === false;
 var isTransientNetworkError = (error) => {
   const message = error.message?.toLowerCase?.() ?? "";
@@ -193,13 +198,34 @@ function useTokenLifecycle(options) {
   const [isRefreshing, setIsRefreshing] = react.useState(false);
   const [isRefreshTokenExpired, setIsRefreshTokenExpired] = react.useState(false);
   const isRefreshingRef = react.useRef(false);
+  const isMountedRef = react.useRef(true);
   const hasCheckedOnStartup = react.useRef(false);
-  const supportsRefreshTokens = config.silentRenew?.useRefreshToken !== false;
+  const allowIframeFallback = config.silentRenew?.allowIframeFallback === true;
   const [pendingRetry, setPendingRetry] = react.useState(null);
   const deferredRefreshReasonRef = react.useRef(null);
+  const transientRetryAttemptsRef = react.useRef(0);
   const enqueueRetry = react.useCallback((reason) => {
     setPendingRetry((current) => current === reason ? current : reason);
   }, []);
+  const transientRetry = config.silentRenew?.transientRetry;
+  const maxTransientRetries = Math.max(
+    0,
+    transientRetry?.maxAttempts ?? DEFAULT_MAX_TRANSIENT_RETRIES
+  );
+  const retryInitialDelayMs = Math.max(
+    0,
+    transientRetry?.initialDelayMs ?? DEFAULT_RETRY_INITIAL_DELAY_MS
+  );
+  const retryMaxDelayMs = Math.max(
+    retryInitialDelayMs,
+    transientRetry?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS
+  );
+  react.useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
   const log = react.useCallback(
     (message, ...args) => {
       if (debug) {
@@ -269,6 +295,7 @@ function useTokenLifecycle(options) {
       log("Starting token refresh");
       await auth.signinSilent();
       log("Token refresh successful");
+      transientRetryAttemptsRef.current = 0;
       onRefreshSuccess?.();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
@@ -291,7 +318,15 @@ function useTokenLifecycle(options) {
         deferredRefreshReasonRef.current = reason;
         if (reason === "offline") {
           log("Token refresh deferred because device is offline");
+          transientRetryAttemptsRef.current = 0;
         } else {
+          if (transientRetryAttemptsRef.current >= maxTransientRetries) {
+            deferredRefreshReasonRef.current = null;
+            log("Token refresh retry limit reached:", err.message);
+            onRefreshError?.(err);
+            return;
+          }
+          transientRetryAttemptsRef.current += 1;
           log(
             "Token refresh failed due to transient network issue, will retry automatically:",
             err.message
@@ -317,7 +352,8 @@ function useTokenLifecycle(options) {
     onRefreshTokenExpired,
     enqueueRetry,
     getStorageKey,
-    log
+    log,
+    maxTransientRetries
   ]);
   const shouldRefreshOnResume = react.useCallback((reason) => {
     const silentRenewEnabled = config.silentRenew?.enabled !== false;
@@ -334,7 +370,7 @@ function useTokenLifecycle(options) {
     if (!auth.user) {
       return false;
     }
-    if (supportsRefreshTokens && !hasRefreshToken) {
+    if (!hasRefreshToken && !allowIframeFallback) {
       log("Skipping resume token check because no refresh token is available:", reason);
       return false;
     }
@@ -348,7 +384,7 @@ function useTokenLifecycle(options) {
     config.silentRenew?.enabled,
     config.silentRenew?.refreshOnResume,
     config.silentRenew?.refreshStrategy,
-    supportsRefreshTokens,
+    allowIframeFallback,
     log
   ]);
   const checkAndRefreshTokens = react.useCallback(async () => {
@@ -421,10 +457,10 @@ function useTokenLifecycle(options) {
     }
     let cancelled = false;
     const executeRetry = () => {
-      if (cancelled) {
+      if (!isMountedRef.current) {
         return;
       }
-      if (isRefreshing) {
+      if (isRefreshingRef.current) {
         log("Skipping scheduled token refresh retry because a refresh is already in progress");
         return;
       }
@@ -448,19 +484,23 @@ function useTokenLifecycle(options) {
         window.removeEventListener("online", handleOnline);
       };
     }
+    const retryDelay = Math.min(
+      retryInitialDelayMs * 2 ** Math.max(0, transientRetryAttemptsRef.current - 1),
+      retryMaxDelayMs
+    );
     const timeoutId = window.setTimeout(() => {
       if (cancelled) {
         return;
       }
       log("Retrying token refresh after transient network failure delay");
       setPendingRetry(null);
-      executeRetry();
-    }, 5e3);
+      window.setTimeout(executeRetry, 0);
+    }, retryDelay);
     return () => {
       cancelled = true;
       window.clearTimeout(timeoutId);
     };
-  }, [pendingRetry, refreshToken, isRefreshing, log]);
+  }, [pendingRetry, refreshToken, log, retryInitialDelayMs, retryMaxDelayMs]);
   react.useEffect(() => {
     const strategy = config.silentRenew?.refreshStrategy || "both";
     const shouldCheckOnStartup = strategy === "startup" || strategy === "both";
@@ -472,10 +512,7 @@ function useTokenLifecycle(options) {
       return;
     }
     if (!auth.isAuthenticated) {
-      if (!supportsRefreshTokens) {
-        return;
-      }
-      if (!auth.user || !hasRefreshToken) {
+      if (!auth.user || !hasRefreshToken && !allowIframeFallback) {
         return;
       }
     }
@@ -484,7 +521,7 @@ function useTokenLifecycle(options) {
       "Running startup token check with strategy:",
       strategy,
       "using refresh token:",
-      !auth.isAuthenticated && supportsRefreshTokens
+      !auth.isAuthenticated && hasRefreshToken
     );
     checkAndRefreshTokens().catch((error) => {
       log("Startup token check failed:", error);
@@ -494,7 +531,7 @@ function useTokenLifecycle(options) {
     auth.isLoading,
     auth.user,
     config.silentRenew?.refreshStrategy,
-    supportsRefreshTokens,
+    allowIframeFallback,
     checkAndRefreshTokens,
     log
   ]);
@@ -534,11 +571,11 @@ function useTokenLifecycle(options) {
     if (hasCheckedOnStartup.current) {
       const hasUser = Boolean(auth.user);
       const hasRefreshToken = Boolean(auth.user?.refresh_token);
-      if (!auth.isAuthenticated && (!supportsRefreshTokens || !hasUser || !hasRefreshToken)) {
+      if (!auth.isAuthenticated && (!hasUser || !hasRefreshToken && !allowIframeFallback)) {
         hasCheckedOnStartup.current = false;
       }
     }
-  }, [auth.isAuthenticated, auth.user, supportsRefreshTokens]);
+  }, [auth.isAuthenticated, auth.user, allowIframeFallback]);
   react.useEffect(() => {
     if (auth.user && !auth.isLoading) {
       storeFirstLoginTime();