# 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)