206 lines
5.2 KiB
Markdown
206 lines
5.2 KiB
Markdown
# 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)
|