setup

docs/KEYCLOAK_ENV.md

@@ -0,0 +1,205 @@
+# Keycloak Environment Variables
+
+This document describes the environment variables required for Keycloak integration.
+
+## Required Environment Variables
+
+### Keycloak Configuration
+
+```bash
+# Keycloak Realm
+KEYCLOAK_REALM=alla-os
+
+# Keycloak Auth Server URL
+KEYCLOAK_AUTH_SERVER_URL=https://keycloak.example.com/auth
+
+# Keycloak Client ID
+KEYCLOAK_CLIENT_ID=alla-os-frontend
+
+# Keycloak Client Secret (for confidential clients)
+KEYCLOAK_CLIENT_SECRET=your-client-secret-here
+
+# Keycloak Public Key (for JWT verification)
+KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----"
+```
+
+### Database Configuration
+
+```bash
+# Database URL
+DATABASE_URL=postgresql://user:password@localhost:5432/alla_os_db
+```
+
+### Application Configuration
+
+```bash
+# Node Environment
+NODE_ENV=development
+
+# Application URL
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# API Base URL
+NEXT_PUBLIC_API_URL=http://localhost:3001
+```
+
+## Getting Keycloak Configuration
+
+### 1. Get Public Key from Keycloak
+
+You can get the public key from Keycloak's realm public key endpoint:
+
+```bash
+# For realm "alla-os"
+curl https://keycloak.example.com/auth/realms/alla-os/protocol/openid-connect/certs
+```
+
+Or from the Keycloak Admin Console:
+
+1. Login to Keycloak Admin Console
+2. Go to Realm Settings → Keys
+3. Copy the "Public Key" (without the header/footer)
+
+### 2. Create Client in Keycloak
+
+1. Login to Keycloak Admin Console
+2. Go to Clients → Create
+3. Fill in client details:
+   - Client ID: `alla-os-frontend` (or your preferred ID)
+   - Client Protocol: `openid-connect`
+   - Root URL: `http://localhost:3000` (your app URL)
+4. Configure client:
+   - Access Type: `public` (for SPA) or `confidential` (for backend)
+   - Valid Redirect URIs: `http://localhost:3000/*`
+   - Web Origins: `http://localhost:3000`
+5. Save and copy the Client Secret (if confidential)
+
+### 3. Create User Groups
+
+Create groups for branch access in Keycloak:
+
+1. Go to Groups → Create Group
+2. Create groups: `alla`, `onvalla`
+3. Add users to appropriate groups
+4. Users can belong to multiple groups for multi-branch access
+
+## Development Mode
+
+In development mode, the application uses mock authentication:
+
+```bash
+NODE_ENV=development
+```
+
+Mock behavior:
+
+- Default user ID: `mock-user-id`
+- Default groups: `["alla"]`
+- You can override with headers:
+  - `x-mock-user-id: custom-user-id`
+  - `x-mock-groups: alla,onvalla`
+
+## Production Mode
+
+In production mode, the application requires valid Keycloak JWT tokens:
+
+```bash
+NODE_ENV=production
+```
+
+All requests must include:
+
+```bash
+Authorization: Bearer <valid-jwt-token>
+```
+
+## Environment Variable Template
+
+Create a `.env.local` file in your project root:
+
+```env
+# ========================================
+# Keycloak Configuration
+# ========================================
+KEYCLOAK_REALM=alla-os
+KEYCLOAK_AUTH_SERVER_URL=https://keycloak.example.com/auth
+KEYCLOAK_CLIENT_ID=alla-os-frontend
+KEYCLOAK_CLIENT_SECRET=your-client-secret-here
+KEYCLOAK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----"
+
+# ========================================
+# Database Configuration
+# ========================================
+DATABASE_URL=postgresql://user:password@localhost:5432/alla_os_db
+
+# ========================================
+# Application Configuration
+# ========================================
+NODE_ENV=development
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:3001
+```
+
+## Testing Without Keycloak
+
+For local development without Keycloak, you can use mock mode:
+
+```bash
+# In .env.local
+NODE_ENV=development
+
+# The middleware will automatically use mock authentication
+# No JWT token required
+```
+
+### Testing with Mock Headers
+
+```bash
+curl -H "x-mock-user-id: test-user-123" \
+     -H "x-mock-groups: alla,onvalla" \
+     -H "x-branch-id: <branch-uuid>" \
+     http://localhost:3000/api/customers
+```
+
+## Security Notes
+
+1. **Never commit `.env` files** - Add to `.gitignore`
+2. **Use strong secrets** - Generate random client secrets
+3. **Rotate keys regularly** - Update public key when Keycloak rotates
+4. **Use HTTPS in production** - All Keycloak communication must be secure
+5. **Validate tokens** - Verify JWT signature with public key
+6. **Check expiration** - Reject expired tokens
+7. **Limit token lifetime** - Short-lived tokens are more secure
+
+## Troubleshooting
+
+### Issue: "Unauthorized: No user ID found"
+
+**Solution:** Ensure `Authorization` header is present with valid JWT token
+
+### Issue: "Keycloak: Token expired"
+
+**Solution:** Refresh the token or log in again
+
+### Issue: "Forbidden: User has no branch access"
+
+**Solution:** Add user to appropriate Keycloak groups (alla, onvalla)
+
+### Issue: "Keycloak: Failed to decode token"
+
+**Solution:** Verify token format and ensure it's a valid JWT
+
+### Issue: "Cannot find module 'jsonwebtoken'"
+
+**Solution:** Install dependencies:
+
+```bash
+npm install jsonwebtoken
+npm install -D @types/jsonwebtoken
+```
+
+## References
+
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [JWT.io](https://jwt.io/) - JWT Debugger
+- [Keycloak JWT Validation](https://www.keycloak.org/docs/latest/securing_apps/#_token-introspection)