antaeus.keycloak.react 2.1.3 → 2.2.0

package/README.md

@@ -187,7 +187,7 @@ interface KeycloakConfig {
   authority: string;         // Required
   clientId: string;          // Required
   scope?: string;            // Default: 'openid profile email offline_access'
-  
+
   features?: {
     autoRefresh?: boolean;       // Default: true
     sessionMonitor?: boolean;    // Default: true
@@ -201,6 +201,13 @@ interface KeycloakConfig {
     showLoadingIndicator?: boolean;         // Default: false
   };
 
+  advanced?: {
+    storageType?: 'session' | 'local';      // Default: 'session'
+    responseType?: string;                  // Default: 'code'
+    codeChallengeMethod?: string;           // Default: 'S256'
+    loadUserInfo?: boolean;                 // Default: true
+  };
+
   events?: {
     onLogin?: (user: User) => void;
     onLogout?: () => void;
@@ -210,6 +217,35 @@ interface KeycloakConfig {
 }
 ```
 
+### Storage Options
+
+By default, the library uses **sessionStorage** which means tokens are cleared when the browser tab is closed. To persist sessions across browser tabs and restarts, use **localStorage**:
+
+```tsx
+<KeycloakProvider
+  authority="https://sso.example.com/realms/myrealm"
+  clientId="my-app"
+  config={{
+    advanced: {
+      storageType: 'local'  // Persist across tabs/restarts
+    }
+  }}
+>
+  <App />
+</KeycloakProvider>
+```
+
+**Storage Comparison:**
+
+| Storage Type | Persistence | Use Case |
+|--------------|-------------|----------|
+| `session` (default) | Cleared when tab closes | Higher security, temporary sessions |
+| `local` | Persists across tabs/restarts | Better UX, permanent sessions |
+
+**Security Considerations:**
+- `sessionStorage`: More secure as tokens are cleared when tab closes
+- `localStorage`: More convenient but tokens persist longer (use `maxRefreshTokenLifetime` to limit)
+
 ## What's New in v2.0.0
 
 - Zero-config setup
@@ -219,10 +255,144 @@ interface KeycloakConfig {
 - Auto-included SessionMonitor
 - Built-in error notifications
 
+## Token Refresh Behavior & Edge Cases
+
+### Understanding 401 vs 403 Errors
+
+The library handles authentication errors intelligently:
+
+**401 Unauthorized** - Token expired or invalid
+- Automatically triggers silent token refresh
+- Retries the failed request once with new token
+- Protected by race condition prevention (1-second cooldown)
+- Only retries when `retryOn401: true` (default)
+
+**403 Forbidden** - Valid token, insufficient permissions
+- Does NOT trigger token refresh (by design)
+- Returns the 403 error to your application
+- Indicates a permissions issue, not an auth issue
+
+```tsx
+// Example: API call with 401 handling
+const { fetchJson } = useProtectedFetch({
+  baseUrl: 'https://api.example.com',
+  retryOn401: true,  // Default: automatically retry after refresh
+});
+
+try {
+  const data = await fetchJson('/api/data');
+} catch (error) {
+  // 401: Already handled automatically
+  // 403: User lacks permissions - handle in your app
+  // Other errors: Network, server errors, etc.
+}
+```
+
+### Race Condition Protection
+
+Multiple concurrent API calls won't cause multiple token refresh attempts:
+
+- First 401 triggers refresh, subsequent calls wait
+- 1-second cooldown prevents rapid retry loops
+- Refresh state shared across all API calls
+- Fresh token always used after refresh completes
+
+### Refresh Token Expiration
+
+If your refresh token expires (exceeds `maxRefreshTokenLifetime`):
+
+1. Library detects expiration (checked every 5 minutes)
+2. User sees "Session Expired" screen
+3. Local storage is cleaned up
+4. User must sign in again
+
+```tsx
+// Configure max lifetime (default: 30 days)
+<KeycloakProvider
+  authority="..."
+  clientId="my-app"
+  config={{
+    silentRenew: {
+      maxRefreshTokenLifetime: 604800,  // 7 days
+    },
+    events: {
+      onRefreshTokenExpired: () => {
+        console.log('Session exceeded max lifetime');
+        // Optional: show custom message
+      }
+    }
+  }}
+/>
+```
+
+### Startup Token Refresh
+
+When your app loads with an existing session:
+
+- **Strategy: 'startup'** - Checks token immediately, refreshes if needed
+- **Strategy: 'on-demand'** - Waits for first API call to fail
+- **Strategy: 'both'** (recommended) - Proactive startup check + 401 retry
+
+```tsx
+// Recommended for best UX
+config={{
+  silentRenew: {
+    refreshStrategy: 'both',
+    thresholdSeconds: 300,  // Refresh when <5min remaining
+  }
+}}
+```
+
+### Edge Case: Refresh Fails During Startup
+
+If token refresh fails when the app loads:
+
+- `onRefreshError` callback is triggered
+- Error is logged (if debug enabled)
+- App continues to render (non-blocking)
+- User can manually sign in
+
+```tsx
+<KeycloakProvider
+  authority="..."
+  clientId="my-app"
+  debug={true}  // Enable console logging
+  config={{
+    events: {
+      onSilentRenewError: (error) => {
+        console.error('Token refresh failed:', error);
+        // Optional: show notification to user
+      }
+    }
+  }}
+/>
+```
+
+### Preventing Infinite Retry Loops
+
+The library has multiple safeguards:
+
+1. Only retries each failed request **once**
+2. Uses `refreshInProgressRef` flag to prevent concurrent refreshes
+3. 1-second cooldown between refresh attempts
+4. Refresh token expiration check prevents dead-end retries
+
+### Network Offline Scenarios
+
+When network is unavailable:
+
+- Token refresh will fail (network error)
+- Original API request fails
+- `onRefreshError` / `onSilentRenewError` callbacks triggered
+- No infinite retry loop (protected by cooldown)
+- User can retry manually when online
+
 ## Troubleshooting
 
 ### 401 errors after app reopens?
 
+Enable startup refresh strategy:
+
 ```tsx
 config={{ silentRenew: { refreshStrategy: 'both' } }}
 ```
@@ -235,7 +405,45 @@ Make sure offline_access scope is included:
 config={{ scope: 'openid profile email offline_access' }}
 ```
 
+### Getting 403 errors on API calls?
+
+This is a permissions issue, not authentication:
+
+```tsx
+// 403 means valid token but insufficient permissions
+// Check user roles/permissions in Keycloak
+const { hasRole } = useRoles();
+
+if (!hasRole('admin')) {
+  return <div>Access denied</div>;
+}
+```
+
+### Token refreshing too frequently?
+
+Increase the threshold:
+
+```tsx
+config={{
+  silentRenew: {
+    thresholdSeconds: 600,  // Refresh when <10min remaining (default: 5min)
+  }
+}}
+```
+
+### Want to disable automatic retry on 401?
+
+```tsx
+const { fetchJson } = useProtectedFetch({
+  baseUrl: 'https://api.example.com',
+  retryOn401: false,  // Disable automatic retry
+  onUnauthorized: () => {
+    console.log('Got 401, handle manually');
+  }
+});
+```
+
 ## License
 
-MIT � Saeed Aghdam
+MIT � Saeed Aghdam
 

package/dist/index.d.mts

@@ -163,6 +163,13 @@ interface AdvancedOidcOptions {
      * @default false
      */
     automaticSilentSignIn?: boolean;
+    /**
+     * Storage mechanism for tokens and user data
+     * - 'session': Use sessionStorage (cleared when tab closes)
+     * - 'local': Use localStorage (persists across browser sessions)
+     * @default 'session'
+     */
+    storageType?: 'session' | 'local';
 }
 
 /**
@@ -319,6 +326,21 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  * </KeycloakProvider>
  * ```
  *
+ * @example Using localStorage to persist sessions across tabs/windows
+ * ```tsx
+ * <KeycloakProvider
+ *   authority="https://sso.example.com/realms/myrealm"
+ *   clientId="my-app"
+ *   config={{
+ *     advanced: {
+ *       storageType: 'local', // Use localStorage instead of sessionStorage
+ *     }
+ *   }}
+ * >
+ *   <YourApp />
+ * </KeycloakProvider>
+ * ```
+ *
  * ## Full-Config Mode (Advanced)
  *
  * Complete control over all configuration options.

package/dist/index.d.ts

@@ -163,6 +163,13 @@ interface AdvancedOidcOptions {
      * @default false
      */
     automaticSilentSignIn?: boolean;
+    /**
+     * Storage mechanism for tokens and user data
+     * - 'session': Use sessionStorage (cleared when tab closes)
+     * - 'local': Use localStorage (persists across browser sessions)
+     * @default 'session'
+     */
+    storageType?: 'session' | 'local';
 }
 
 /**
@@ -319,6 +326,21 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  * </KeycloakProvider>
  * ```
  *
+ * @example Using localStorage to persist sessions across tabs/windows
+ * ```tsx
+ * <KeycloakProvider
+ *   authority="https://sso.example.com/realms/myrealm"
+ *   clientId="my-app"
+ *   config={{
+ *     advanced: {
+ *       storageType: 'local', // Use localStorage instead of sessionStorage
+ *     }
+ *   }}
+ * >
+ *   <YourApp />
+ * </KeycloakProvider>
+ * ```
+ *
  * ## Full-Config Mode (Advanced)
  *
  * Complete control over all configuration options.

package/dist/index.js

@@ -2,10 +2,10 @@
 
 var react = require('react');
 var reactOidcContext = require('react-oidc-context');
+var oidcClientTs = require('oidc-client-ts');
 var jsxRuntime = require('react/jsx-runtime');
 var reactRouterDom = require('react-router-dom');
 var qrcode_react = require('qrcode.react');
-var oidcClientTs = require('oidc-client-ts');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/components/KeycloakProvider.tsx
@@ -36,7 +36,8 @@ var defaultConfig = {
     responseType: "code",
     codeChallengeMethod: "S256",
     loadUserInfo: true,
-    automaticSilentSignIn: false
+    automaticSilentSignIn: false,
+    storageType: "session"
   },
   events: {}
 };
@@ -53,6 +54,8 @@ var KeycloakConfigBuilder = class {
   static build(userConfig) {
     this.validate(userConfig);
     const config = this.mergeWithDefaults(userConfig);
+    const storageType = config.advanced.storageType || "session";
+    const storage = storageType === "local" ? window.localStorage : window.sessionStorage;
     const oidcSettings = {
       authority: config.authority,
       client_id: config.clientId,
@@ -63,6 +66,8 @@ var KeycloakConfigBuilder = class {
       automaticSilentRenew: config.silentRenew.enabled,
       loadUserInfo: config.advanced.loadUserInfo,
       silent_redirect_uri: config.silentRenew.silentRedirectUri,
+      // Configure storage for user data and tokens
+      userStore: new oidcClientTs.WebStorageStateStore({ store: storage }),
       // Add PKCE support (required for public clients)
       ...config.advanced.codeChallengeMethod && {
         response_mode: "query"