antaeus.keycloak.react 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,652 @@
+# 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)
+
+## 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
+
+```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',
+    }}
+  >
+    <App />
+  </KeycloakProvider>
+);
+```
+
+### 2. Use pre-built UI components
+
+```tsx
+// App.tsx
+import { useAuth, LoginButton, LogoutButton, UserProfile } from 'antaeus.keycloak.react';
+
+function App() {
+  const auth = useAuth();
+
+  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>
+    );
+  }
+
+  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>
+  );
+}
+```
+
+### 3. Protect routes
+
+```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>
+  );
+}
+```
+
+## Configuration
+
+### Basic Configuration
+
+```tsx
+<KeycloakProvider
+  config={{
+    authority: 'https://sso.example.com/realms/myrealm',
+    clientId: 'my-app',
+  }}
+>
+  <App />
+</KeycloakProvider>
+```
+
+### Advanced 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
+    },
+
+    // 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),
+    },
+  }}
+  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
+
+#### `ProtectedRoute`
+
+Component for protecting routes that require authentication and/or specific roles.
+
+**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
+
+### Hooks
+
+#### `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 data = await fetchJson<User[]>('/api/users');
+```
+
+### 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
+
+#### `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
+
+**Example:**
+```tsx
+<DeviceLogin
+  apiBaseUrl="http://localhost:5000"
+  onSuccess={(user) => navigate('/dashboard')}
+/>
+```
+
+## Examples
+
+### Role-Based Access
+
+```tsx
+import { useRoles } from 'antaeus.keycloak.react';
+
+function MyComponent() {
+  const { roles, hasRole, hasAnyRole } = useRoles();
+
+  return (
+    <div>
+      <p>Your roles: {roles.join(', ')}</p>
+
+      {hasRole('admin') && <AdminPanel />}
+
+      {hasAnyRole(['editor', 'moderator']) && <EditButton />}
+    </div>
+  );
+}
+```
+
+### 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
+
+```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
+
+```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!');
+        }}
+      />
+    </>
+  );
+}
+```
+
+### 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);
+      }}
+    />
+  );
+}
+```
+
+### Environment Variables
+
+```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.
+
+---
+
+## 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
+
+```tsx
+<KeycloakProvider
+  config={{
+    authority: 'https://keycloak.example.com/realms/myapp',  // ← HTTPS!
+    // Never use http:// in production
+  }}
+>
+```
+
+### 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.
+
+### 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
+
+```tsx
+const { signoutRedirect } = useAuth();
+
+// This logs out from Keycloak AND your app
+await signoutRedirect();
+```
+
+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
+
+- [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)