litoral05Backend Gateway
Version: v1.0.0
Overview
Backend Gateway is the central access layer between client applications (Tauri, Web, Mobile) and site-specific backend services.
The gateway provides:
- Authentication
- Authorization
- Multi-client routing
- Backend proxying
- Centralized user management
- Secure access through JWT
The goal is to expose a single public endpoint while keeping site backends private behind WireGuard.
Architecture
Tauri/Web App
│
▼
Backend Gateway (VPS)
│
▼
WireGuard Tunnel
│
▼
Site Backend
│
▼
PLC / Modbus / VNC / Local Services
Client applications never communicate directly with site backends.
All traffic goes through the gateway.
Technology Stack
- Java 21
- Spring Boot 3
- Spring Security
- JWT (JJWT)
- Flyway
- SQLite
- WireGuard
Database
SQLite database:
./data/backend-gateway.db
Schema managed exclusively through Flyway migrations.
Hibernate schema generation is disabled.
spring:
jpa:
hibernate:
ddl-auto: none
Authentication
Authentication uses username/password credentials.
Endpoint:
POST /auth/login
Request:
{
"username": "admin",
"password": "admin123"
}
Response:
{
"accessToken": "...",
"tokenType": "Bearer",
"userId": 1,
"clientId": 1,
"clientName": "dev-local",
"username": "admin",
"role": "ADMIN"
}
Passwords are stored using BCrypt.
Authorization
Roles currently supported:
ADMIN
CLIENT_USER
ADMIN:
- Manage clients
- Manage users
- Access backend proxy
CLIENT_USER:
- Access backend proxy
- No administrative access
JWT
JWT authentication is stateless.
Claims:
{
"sub": "username",
"userId": 1,
"clientId": 1,
"role": "ADMIN"
}
Protected requests require:
Authorization: Bearer <token>
Multi-Client Architecture
Each user belongs to a client.
Each client defines a backend endpoint:
client
└─ backendBaseUrl
Example:
Client:
dev-local
Backend:
http://10.100.1.2:18450
When a user authenticates:
JWT
└─ clientId
The gateway uses the clientId to determine which backend should receive proxied requests.
Backend Proxy
Proxy endpoint:
/api/backend/**
Example:
GET /api/backend/actuator/health
Gateway flow:
JWT
└─ clientId
clientId
└─ backendBaseUrl
backendBaseUrl
└─ target backend request
Users never see backend addresses.
Flyway Migrations
Current migrations:
V1__create_clients.sql
V2__create_users.sql
V3__bootstrap_default_admin.sql
Flyway automatically applies migrations on startup.
Bootstrap Administrator
A default administrator is created automatically on a fresh installation.
Default credentials:
Username: admin
Password: admin123
IMPORTANT:
Change this password immediately in production.
Environment Variables
Required:
JWT_SECRET=<secret>
Optional:
JWT_EXPIRATION_MINUTES=1440
Example:
JWT_SECRET=very-long-random-production-secret
JWT_EXPIRATION_MINUTES=1440
Configuration:
jwt:
secret: ${JWT_SECRET}
expiration-minutes: ${JWT_EXPIRATION_MINUTES:1440}
VPS Deployment
Required directory:
backend-gateway/
├── data/
├── target/
├── .env
Database location:
./data/backend-gateway.db
The data directory must exist before startup.
Example:
mkdir -p data
Current Features (v1.0.0)
Implemented:
- JWT Authentication
- BCrypt Passwords
- Role Authorization
- Multi-Client Support
- Client Management
- User Management
- Backend Proxy
- Flyway Migrations
- Bootstrap Admin User
- Environment-Based Secrets
- SQLite Persistence
Planned Features
v1.1
- Change Password Endpoint
- Disable User Endpoint
- Disable Client Endpoint
- Update Client Backend URL
Future
- WebSocket Proxy
- VNC Proxy Support
- Audit Logging
- Refresh Tokens
- User Password Reset
- Client Administration UI
Security Notes
- Never commit .env files.
- Never store JWT secrets in source control.
- Always use HTTPS in production.
- Change bootstrap administrator credentials after installation.
- Keep site backends private behind WireGuard.
Status
Current release:
v1.0.0
State:
Production deployable