nextjs-elysia-allaos/docs/KEYCLOAK_ENV.md

Keycloak Environment Variables

This document describes the environment variables required for Keycloak integration.

Required Environment Variables

Keycloak Configuration

# 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

# Database URL
DATABASE_URL=postgresql://user:password@localhost:5432/alla_os_db

Application Configuration

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

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

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:

NODE_ENV=production

All requests must include:

Authorization: Bearer <valid-jwt-token>

Environment Variable Template

Create a .env.local file in your project root:

# ========================================
# 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:

# In .env.local
NODE_ENV=development

# The middleware will automatically use mock authentication
# No JWT token required

Testing with Mock Headers

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:

npm install jsonwebtoken
npm install -D @types/jsonwebtoken

References

• Keycloak Documentation
• JWT.io - JWT Debugger
• Keycloak JWT Validation