litoral05
374 lines
4.4 KiB
Markdown
374 lines
4.4 KiB
Markdown
# Backend 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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
./data/backend-gateway.db
|
|
```
|
|
|
|
Schema managed exclusively through Flyway migrations.
|
|
|
|
Hibernate schema generation is disabled.
|
|
|
|
```yaml
|
|
spring:
|
|
jpa:
|
|
hibernate:
|
|
ddl-auto: none
|
|
```
|
|
|
|
---
|
|
|
|
# Authentication
|
|
|
|
Authentication uses username/password credentials.
|
|
|
|
Endpoint:
|
|
|
|
```http
|
|
POST /auth/login
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"username": "admin",
|
|
"password": "admin123"
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"accessToken": "...",
|
|
"tokenType": "Bearer",
|
|
"userId": 1,
|
|
"clientId": 1,
|
|
"clientName": "dev-local",
|
|
"username": "admin",
|
|
"role": "ADMIN"
|
|
}
|
|
```
|
|
|
|
Passwords are stored using BCrypt.
|
|
|
|
---
|
|
|
|
# Authorization
|
|
|
|
Roles currently supported:
|
|
|
|
```text
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"sub": "username",
|
|
"userId": 1,
|
|
"clientId": 1,
|
|
"role": "ADMIN"
|
|
}
|
|
```
|
|
|
|
Protected requests require:
|
|
|
|
```http
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
---
|
|
|
|
# Multi-Client Architecture
|
|
|
|
Each user belongs to a client.
|
|
|
|
Each client defines a backend endpoint:
|
|
|
|
```text
|
|
client
|
|
└─ backendBaseUrl
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
Client:
|
|
dev-local
|
|
|
|
Backend:
|
|
http://10.100.1.2:18450
|
|
```
|
|
|
|
When a user authenticates:
|
|
|
|
```text
|
|
JWT
|
|
└─ clientId
|
|
```
|
|
|
|
The gateway uses the clientId to determine which backend should receive proxied requests.
|
|
|
|
---
|
|
|
|
# Backend Proxy
|
|
|
|
Proxy endpoint:
|
|
|
|
```http
|
|
/api/backend/**
|
|
```
|
|
|
|
Example:
|
|
|
|
```http
|
|
GET /api/backend/actuator/health
|
|
```
|
|
|
|
Gateway flow:
|
|
|
|
```text
|
|
JWT
|
|
└─ clientId
|
|
|
|
clientId
|
|
└─ backendBaseUrl
|
|
|
|
backendBaseUrl
|
|
└─ target backend request
|
|
```
|
|
|
|
Users never see backend addresses.
|
|
|
|
---
|
|
|
|
# Flyway Migrations
|
|
|
|
Current migrations:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
Username: admin
|
|
Password: admin123
|
|
```
|
|
|
|
IMPORTANT:
|
|
|
|
Change this password immediately in production.
|
|
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
Required:
|
|
|
|
```env
|
|
JWT_SECRET=<secret>
|
|
```
|
|
|
|
Optional:
|
|
|
|
```env
|
|
JWT_EXPIRATION_MINUTES=1440
|
|
```
|
|
|
|
Example:
|
|
|
|
```env
|
|
JWT_SECRET=very-long-random-production-secret
|
|
JWT_EXPIRATION_MINUTES=1440
|
|
```
|
|
|
|
Configuration:
|
|
|
|
```yaml
|
|
jwt:
|
|
secret: ${JWT_SECRET}
|
|
expiration-minutes: ${JWT_EXPIRATION_MINUTES:1440}
|
|
```
|
|
|
|
---
|
|
|
|
# VPS Deployment
|
|
|
|
Required directory:
|
|
|
|
```text
|
|
backend-gateway/
|
|
├── data/
|
|
├── target/
|
|
├── .env
|
|
```
|
|
|
|
Database location:
|
|
|
|
```text
|
|
./data/backend-gateway.db
|
|
```
|
|
|
|
The data directory must exist before startup.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
v1.0.0
|
|
```
|
|
|
|
State:
|
|
|
|
```text
|
|
Production deployable
|
|
```
|