antaeus.keycloak.react 1.0.6 → 2.0.0

package/README.md

@@ -1,652 +1,241 @@
 # antaeus.keycloak.react
 
-> Complete Keycloak integration for React with minimal configuration
-
-[![npm version](https://img.shields.io/npm/v/antaeus.keycloak.react.svg)](https://www.npmjs.com/package/antaeus.keycloak.react)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Features
-
-### Authentication & Authorization
-- ✅ **Authorization Code + PKCE** - Secure authentication flow
-- ✅ **Device Flow Support** - For TVs, IoT devices, and CLIs
-- ✅ **Protected Routes** - Easy route protection with role checking
-- ✅ **Automatic Token Refresh** - Silent token renewal
-- ✅ **Role-Based Access Control** - Built-in role checking utilities
-
-### UI Components
-- ✅ **Pre-built Components** - LoginButton, LogoutButton, UserProfile
-- ✅ **Session Monitor** - Real-time session countdown with warnings
-- ✅ **Device Login UI** - QR code display with automatic polling
-- ✅ **Professional Styling** - Production-ready CSS with dark mode
-
-### Developer Experience
-- ✅ **TypeScript Support** - Full type safety
-- ✅ **Minimal Configuration** - Works with sensible defaults
-- ✅ **Protected Fetch Hook** - API calls with automatic token injection
-- ✅ **Tiny Bundle** - Only 28 KB (minified, before gzip)
+Production-ready Keycloak integration for React with zero-config setup
 
 ## Installation
 
 ```bash
 npm install antaeus.keycloak.react
-# or
-yarn add antaeus.keycloak.react
-# or
-pnpm add antaeus.keycloak.react
 ```
 
-## Quick Start
-
-### 1. Import styles and wrap your app with KeycloakProvider
+## Quick Start (Zero-Config)
 
 ```tsx
-// main.tsx
 import { KeycloakProvider } from 'antaeus.keycloak.react';
-import 'antaeus.keycloak.react/styles.css'; // Import CSS
 
 ReactDOM.createRoot(document.getElementById('root')).render(
   <KeycloakProvider
-    config={{
-      authority: 'https://sso.example.com/realms/myrealm',
-      clientId: 'my-app',
-    }}
+    authority="https://sso.example.com/realms/myrealm"
+    clientId="my-app"
   >
     <App />
   </KeycloakProvider>
 );
 ```
 
-### 2. Use pre-built UI components
+That's it! You now have full authentication with automatic token refresh.
+
+## Features
+
+- Zero-config setup
+- Automatic token lifecycle management
+- Token refresh on app startup
+- Silent token renewal
+- Session monitoring UI
+- Protected routes
+- API hooks with auto-auth
+- Device flow support
+- TypeScript support
+
+## Usage in Components
 
 ```tsx
-// App.tsx
-import { useAuth, LoginButton, LogoutButton, UserProfile } from 'antaeus.keycloak.react';
+import { useAuth, useProtectedFetch } from 'antaeus.keycloak.react';
 
-function App() {
+function MyComponent() {
   const auth = useAuth();
+  const { fetchJson } = useProtectedFetch({ baseUrl: 'https://api.example.com' });
 
-  if (auth.isLoading) {
-    return <div>Loading...</div>;
-  }
-
-  if (!auth.isAuthenticated) {
-    return (
-      <div>
-        <h1>Welcome to My App</h1>
-        <LoginButton variant="primary" size="large">
-          Get Started
-        </LoginButton>
-      </div>
-    );
-  }
+  const loadData = async () => {
+    const data = await fetchJson('/api/data');  // Token added automatically
+    console.log(data);
+  };
 
-  return (
-    <div>
-      <header>
-        <UserProfile showAvatar showEmail showRoles />
-        <LogoutButton />
-      </header>
-      <main>
-        <h1>Welcome, {auth.user?.profile?.name}</h1>
-        <p>You are logged in!</p>
-      </main>
-    </div>
-  );
+  return <button onClick={loadData}>Load</button>;
 }
 ```
 
-### 3. Protect routes
+## Configuration Modes
+
+### 1. Zero-Config (Recommended)
 
 ```tsx
-import { ProtectedRoute } from 'antaeus.keycloak.react';
-import { BrowserRouter, Route, Routes } from 'react-router-dom';
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/" element={<HomePage />} />
-
-        <Route
-          path="/dashboard"
-          element={
-            <ProtectedRoute>
-              <DashboardPage />
-            </ProtectedRoute>
-          }
-        />
-
-        <Route
-          path="/admin"
-          element={
-            <ProtectedRoute requiredRoles={['admin']}>
-              <AdminPage />
-            </ProtectedRoute>
-          }
-        />
-      </Routes>
-    </BrowserRouter>
-  );
-}
+<KeycloakProvider authority="..." clientId="my-app">
+  <App />
+</KeycloakProvider>
 ```
 
-## Configuration
+### 2. With Preset
 
-### Basic Configuration
+```tsx
+<KeycloakProvider
+  authority="..."
+  clientId="my-app"
+  preset="mobile"  // 'default' | 'mobile' | 'high-security' | 'long-running'
+>
+  <App />
+</KeycloakProvider>
+```
+
+### 3. With Overrides
 
 ```tsx
 <KeycloakProvider
+  authority="..."
+  clientId="my-app"
   config={{
-    authority: 'https://sso.example.com/realms/myrealm',
-    clientId: 'my-app',
+    silentRenew: {
+      maxRefreshTokenLifetime: 604800,  // 7 days
+      showLoadingIndicator: true,
+    }
   }}
 >
   <App />
 </KeycloakProvider>
 ```
 
-### Advanced Configuration
+### 4. Full Configuration
 
 ```tsx
 <KeycloakProvider
   config={{
     authority: 'https://sso.example.com/realms/myrealm',
     clientId: 'my-app',
-    redirectUri: window.location.origin,
-    postLogoutRedirectUri: window.location.origin,
     scope: 'openid profile email offline_access',
-
-    // Feature flags
-    features: {
-      autoRefresh: true,
-    },
-
-    // Silent token renewal
     silentRenew: {
-      enabled: true,
-      thresholdSeconds: 300, // Renew 5 minutes before expiry
+      refreshStrategy: 'both',
+      maxRefreshTokenLifetime: 2592000,
     },
-
-    // Event callbacks
     events: {
-      onLogin: (user) => console.log('User logged in', user),
-      onLogout: () => console.log('User logged out'),
-      onTokenExpired: () => console.log('Token expired'),
-      onError: (error) => console.error('Auth error', error),
-    },
+      onLogin: (user) => console.log('Logged in', user),
+    }
   }}
-  debug={true} // Enable debug logging
 >
   <App />
 </KeycloakProvider>
 ```
 
-## API Reference
-
-### Components
-
-#### `KeycloakProvider`
-
-Main provider component that wraps your application.
-
-**Props:**
-- `config` (required): Keycloak configuration
-- `children` (required): Child components
-- `loadingComponent` (optional): Custom loading component
-- `errorComponent` (optional): Custom error component
-- `debug` (optional): Enable debug logging
+## Configuration Presets
 
-#### `ProtectedRoute`
+| Preset | Session Lifetime | Best For |
+|--------|------------------|----------|
+| default | 30 days | Most web apps |
+| mobile | 30 days | PWA/Mobile apps |
+| high-security | 24 hours | Banking, healthcare |
+| long-running | 7 days | Desktop apps |
 
-Component for protecting routes that require authentication and/or specific roles.
+## Token Refresh Strategies
 
-**Props:**
-- `children` (required): Components to render when authorized
-- `requiredRoles` (optional): Array of required roles
-- `requireAllRoles` (optional): Require all roles (AND logic) vs any role (OR logic)
-- `loadingComponent` (optional): Custom loading component
-- `unauthorizedComponent` (optional): Custom unauthorized component
-- `redirectTo` (optional): Redirect path when not authenticated (default: '/login')
-- `onUnauthorized` (optional): Callback when access is denied
+- **startup**: Check on app startup
+- **on-demand**: Only when API returns 401
+- **both** (recommended): Startup + 401 retry
 
-### Hooks
+## React Hooks
 
-#### `useAuth()`
+### useAuth()
 
-Main authentication hook.
-
-**Returns:**
-- `user`: Current user object
-- `isAuthenticated`: Whether user is authenticated
-- `isLoading`: Whether authentication is in progress
-- `error`: Authentication error if any
-- `signinRedirect()`: Trigger login redirect
-- `signoutRedirect()`: Trigger logout redirect
-- And more...
-
-#### `useRoles()`
-
-Role checking utilities.
-
-**Returns:**
-- `roles`: Array of user's realm roles
-- `hasRole(role)`: Check if user has a specific role
-- `hasAnyRole(roles)`: Check if user has any of the roles
-- `hasAllRoles(roles)`: Check if user has all the roles
-- `getClientRoles(clientId)`: Get client-specific roles
-
-#### `useProtectedFetch()`
-
-Hook for making authenticated API requests with automatic token injection.
-
-**Options:**
-- `baseUrl` (optional): Base URL for API requests
-- `onUnauthorized` (optional): Callback on 401 errors
-- `retryOn401` (optional): Retry after token refresh (default: true)
-- `headers` (optional): Additional headers for all requests
-
-**Returns:**
-- `fetchJson<T>()`: Fetch and parse JSON with type safety
-- `fetch()`: Raw fetch with token injection
-- `isLoading`: Whether authentication is loading
-
-**Example:**
 ```tsx
-const { fetchJson } = useProtectedFetch({
-  baseUrl: 'http://localhost:5000',
-});
+const auth = useAuth();
 
-const data = await fetchJson<User[]>('/api/users');
+auth.isAuthenticated
+auth.isLoading
+auth.user
+auth.signinRedirect()
+auth.signoutRedirect()
 ```
 
-### UI Components
-
-#### `LoginButton`
-
-Pre-built login button with multiple variants.
-
-**Props:**
-- `variant`: 'primary' | 'secondary' | 'outline' | 'danger' (default: 'primary')
-- `size`: 'small' | 'medium' | 'large' (default: 'medium')
-- `showIcon`: boolean (default: true)
-- `onLoginStart`: Callback before login
-- `disabled`: boolean
-- `className`: Custom CSS class
-- `style`: Inline styles
-
-#### `LogoutButton`
-
-Pre-built logout button.
-
-**Props:**
-- Same as LoginButton
-
-#### `UserProfile`
-
-Displays user information with avatar, name, email, and roles.
-
-**Props:**
-- `showAvatar`: boolean (default: true)
-- `showEmail`: boolean (default: true)
-- `showRoles`: boolean (default: false)
-- `avatarSize`: number (default: 40)
-- `maxRoles`: number (default: 3)
-- `className`: Custom CSS class
-- `style`: Inline styles
+### useProtectedFetch()
 
-#### `SessionMonitor`
-
-Real-time session countdown timer with visual warnings.
-
-**Props:**
-- `position`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'top-right')
-- `warningThreshold`: Seconds for yellow warning (default: 300)
-- `criticalThreshold`: Seconds for red warning (default: 60)
-- `showProgressBar`: boolean (default: true)
-- `minimizable`: boolean (default: true)
-- `startMinimized`: boolean (default: false)
-- `onWarning`: Callback at warning threshold
-- `onCritical`: Callback at critical threshold
-- `onExpired`: Callback when session expires
-
-**Example:**
 ```tsx
-<SessionMonitor
-  position="top-right"
-  warningThreshold={300}
-  criticalThreshold={60}
-  onCritical={(seconds) => alert(`Session expiring in ${seconds} seconds!`)}
-/>
-```
-
-#### `DeviceLogin`
-
-Device flow login component with QR code display.
-
-**Props:**
-- `apiBaseUrl`: Backend API URL (required)
-- `qrCodeSize`: QR code size in pixels (default: 256)
-- `pollingInterval`: Polling interval in seconds (default: 5)
-- `onSuccess`: Callback on successful login
-- `onError`: Callback on error
-- `className`: Custom CSS class
-- `style`: Inline styles
+const { fetchJson, isLoading } = useProtectedFetch({
+  baseUrl: 'https://api.example.com',
+  retryOn401: true,
+});
 
-**Example:**
-```tsx
-<DeviceLogin
-  apiBaseUrl="http://localhost:5000"
-  onSuccess={(user) => navigate('/dashboard')}
-/>
+const data = await fetchJson('/api/data');
 ```
 
-## Examples
-
-### Role-Based Access
+### useRoles()
 
 ```tsx
-import { useRoles } from 'antaeus.keycloak.react';
-
-function MyComponent() {
-  const { roles, hasRole, hasAnyRole } = useRoles();
+const { hasRole, hasAnyRole } = useRoles();
 
-  return (
-    <div>
-      <p>Your roles: {roles.join(', ')}</p>
-
-      {hasRole('admin') && <AdminPanel />}
-
-      {hasAnyRole(['editor', 'moderator']) && <EditButton />}
-    </div>
-  );
+if (hasRole('admin')) {
+  return <AdminPanel />;
 }
 ```
 
-### Multiple Role Requirements
-
-```tsx
-// User needs at least one of these roles
-<ProtectedRoute requiredRoles={['editor', 'moderator', 'admin']}>
-  <EditPage />
-</ProtectedRoute>
-
-// User needs ALL of these roles
-<ProtectedRoute requiredRoles={['verified', 'premium']} requireAllRoles={true}>
-  <PremiumContent />
-</ProtectedRoute>
-```
-
-### Custom Loading/Error States
-
-```tsx
-<ProtectedRoute
-  loadingComponent={<Spinner />}
-  unauthorizedComponent={<AccessDenied />}
->
-  <ProtectedContent />
-</ProtectedRoute>
-```
-
-### Authenticated API Calls
+## Protected Routes
 
 ```tsx
-import { useProtectedFetch } from 'antaeus.keycloak.react';
-
-function UsersList() {
-  const { fetchJson, isLoading } = useProtectedFetch({
-    baseUrl: 'http://localhost:5000',
-  });
-  const [users, setUsers] = useState([]);
-
-  useEffect(() => {
-    fetchJson<User[]>('/api/users')
-      .then(setUsers)
-      .catch(console.error);
-  }, []);
-
-  if (isLoading) return <div>Loading...</div>;
-
-  return (
-    <ul>
-      {users.map(user => (
-        <li key={user.id}>{user.name}</li>
-      ))}
-    </ul>
-  );
-}
-```
-
-### Session Monitoring
+import { ProtectedRoute } from 'antaeus.keycloak.react';
 
-```tsx
-import { SessionMonitor } from 'antaeus.keycloak.react';
-
-function App() {
-  return (
-    <>
-      <YourApp />
-
-      {/* Monitor session and warn before expiration */}
-      <SessionMonitor
-        position="top-right"
-        warningThreshold={600}  // 10 minutes
-        criticalThreshold={120}  // 2 minutes
-        onWarning={() => console.log('Session expiring soon')}
-        onCritical={() => {
-          // Show modal or notification
-          alert('Your session is about to expire!');
-        }}
-      />
-    </>
-  );
-}
+<Route
+  path="/dashboard"
+  element={
+    <ProtectedRoute>
+      <DashboardPage />
+    </ProtectedRoute>
+  }
+/>
 ```
 
-### Device Flow for TVs/IoT
-
-```tsx
-import { DeviceLogin } from 'antaeus.keycloak.react';
-import { useNavigate } from 'react-router-dom';
-
-function TVLoginPage() {
-  const navigate = useNavigate();
-
-  return (
-    <DeviceLogin
-      apiBaseUrl="http://localhost:5000"
-      qrCodeSize={300}
-      pollingInterval={3}
-      onSuccess={(user) => {
-        console.log('User logged in:', user.profile.name);
-        navigate('/dashboard');
-      }}
-      onError={(error) => {
-        console.error('Login failed:', error);
-      }}
-    />
-  );
+## Configuration Reference
+
+```typescript
+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
+  };
+
+  silentRenew?: {
+    enabled?: boolean;                      // Default: true
+    thresholdSeconds?: number;              // Default: 300
+    refreshStrategy?: 'startup' | 'on-demand' | 'both';
+    maxRefreshTokenLifetime?: number;       // Default: 2592000 (30 days)
+    showLoadingIndicator?: boolean;         // Default: false
+  };
+
+  events?: {
+    onLogin?: (user: User) => void;
+    onLogout?: () => void;
+    onTokenExpired?: () => void;
+    onSilentRenewError?: (error: Error) => void;
+  };
 }
 ```
 
-### Environment Variables
+## What's New in v2.0.0
 
-```env
-# .env
-VITE_KEYCLOAK_AUTHORITY=https://sso.example.com/realms/myrealm
-VITE_KEYCLOAK_CLIENT_ID=my-app
-```
-
-```tsx
-import { getConfigFromEnv } from 'antaeus.keycloak.react';
-
-const config = {
-  ...getConfigFromEnv(),
-  // Override or add more config
-};
-
-<KeycloakProvider config={config}>
-  <App />
-</KeycloakProvider>
-```
-
-## Keycloak Server Configuration
-
-This library requires proper Keycloak server configuration. See the comprehensive guide:
-
-📖 **[Keycloak Setup Guide](../../KEYCLOAK_SETUP_GUIDE.md)**
-
-### Quick Keycloak Checklist
-
-Before using this library, ensure your Keycloak server has:
-
-- [ ] **Realm created** with appropriate settings
-- [ ] **Public client created** for your React app with:
-  - Client authentication: `OFF` (public client)
-  - Standard flow: `ON`
-  - PKCE enabled: `S256`
-  - Valid redirect URIs configured
-  - Web origins configured
-- [ ] **Protocol mappers configured**:
-  - Realm roles mapper (`realm_access.roles`)
-  - Audience mapper (pointing to your API)
-- [ ] **Users and roles created**
-- [ ] **CORS enabled** for your frontend origin
-
-See the full guide for detailed step-by-step instructions.
-
----
+- Zero-config setup
+- Automatic token refresh on app startup
+- Configuration presets
+- Enhanced token lifecycle management
+- Auto-included SessionMonitor
+- Built-in error notifications
 
 ## Troubleshooting
 
-### "Invalid redirect_uri" Error
-
-**Cause:** The redirect URL doesn't match Keycloak's allowed URIs.
-
-**Solution:**
-1. Check client configuration in Keycloak
-2. Ensure `redirectUri` in your config matches exactly
-3. Add `http://localhost:5173/*` to Valid Redirect URIs in Keycloak
-
-### Roles Not Showing Up
-
-**Cause:** Missing protocol mapper in Keycloak.
-
-**Solution:**
-1. Add "realm roles mapper" to your client
-2. Configure: Token Claim Name = `realm_access.roles`
-3. Enable: Add to access token, ID token
-
-### CORS Errors
-
-**Cause:** Keycloak not allowing requests from your origin.
-
-**Solution:**
-1. In Keycloak client settings → Web Origins
-2. Add `http://localhost:5173` (or your origin)
-3. Or use `*` for development only
-
-### Token Expired Immediately
-
-**Cause:** Clock skew or short token lifespan.
-
-**Solution:**
-1. Check Keycloak Realm Settings → Tokens
-2. Increase "Access Token Lifespan" (default: 5 min)
-3. Enable automatic token refresh:
-   ```tsx
-   features: { autoRefresh: true }
-   ```
-
-### Device Flow Not Working
-
-**Cause:** Device flow not enabled on Keycloak client.
-
-**Solution:**
-1. In client capabilities, enable: "OAuth 2.0 Device Authorization Grant"
-2. Set device code lifespan and polling interval
-3. Ensure backend API has device flow endpoints configured
-
-For more troubleshooting, see [Keycloak Setup Guide - Troubleshooting](../../KEYCLOAK_SETUP_GUIDE.md#troubleshooting).
-
----
-
-## Security Best Practices
-
-### 1. Always Use HTTPS in Production
+### 401 errors after app reopens?
 
 ```tsx
-<KeycloakProvider
-  config={{
-    authority: 'https://keycloak.example.com/realms/myapp',  // ← HTTPS!
-    // Never use http:// in production
-  }}
->
+config={{ silentRenew: { refreshStrategy: 'both' } }}
 ```
 
-### 2. Don't Store Tokens in localStorage (We Handle This)
-
-The library uses `oidc-client-ts` which stores tokens securely in sessionStorage by default. Never manually store tokens in localStorage as it's vulnerable to XSS attacks.
+### Silent renew not working?
 
-### 3. Use Content Security Policy
-
-Add to your `index.html`:
-```html
-<meta http-equiv="Content-Security-Policy"
-      content="default-src 'self'; connect-src 'self' https://your-keycloak.com;">
-```
-
-### 4. Validate Tokens on the Backend
-
-Frontend authentication is for UX only. Always validate tokens on your backend API:
-```csharp
-// In your .NET API
-builder.Services.AddKeycloakAuthentication(config);
-```
-
-### 5. Use Short-Lived Access Tokens
-
-Configure in Keycloak:
-- Access Token Lifespan: 5 minutes
-- Refresh Token: 30 days
-- Enable automatic refresh in React
-
-### 6. Implement Logout Everywhere
+Make sure offline_access scope is included:
 
 ```tsx
-const { signoutRedirect } = useAuth();
-
-// This logs out from Keycloak AND your app
-await signoutRedirect();
+config={{ scope: 'openid profile email offline_access' }}
 ```
 
-For complete security guidelines, see [Keycloak Setup Guide - Security](../../KEYCLOAK_SETUP_GUIDE.md#security-best-practices).
-
----
-
-## Requirements
-
-- React 18+
-- react-router-dom 6+ (for ProtectedRoute)
-- Modern browser with ES2020 support
-
-## Related Documentation
-
-- 📖 [Keycloak Setup Guide](../../KEYCLOAK_SETUP_GUIDE.md) - Complete Keycloak configuration guide
-- 📖 [Antaeus.Keycloak.AspNetCore](../keycloak-aspnetcore/README.md) - Backend API library
-- 📖 [Quick Start](../../QUICKSTART.md) - Get started quickly
-- 📖 [Deployment Guide](../../DEPLOYMENT.md) - Production deployment
-
 ## License
 
-MIT
-
-## Support
-
-For issues and feature requests, please visit [GitHub Issues](https://github.com/sso/keycloak-react/issues).
-
-### Useful Resources
+MIT � Saeed Aghdam
 
-- [Keycloak Official Documentation](https://www.keycloak.org/docs/latest/)
-- [OAuth 2.0 / OpenID Connect Explained](https://www.oauth.com/)
-- [oidc-client-ts Documentation](https://github.com/authts/oidc-client-ts)