proxmox/docs/04-configuration/CHAIN138_JWT_AUTH_REQUIREMENTS.md

ChainID 138 JWT Authentication Requirements

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Date: December 26, 2024
Status: All RPC containers require JWT authentication

---

Overview

All RPC containers for ChainID 138 require JWT authentication via nginx reverse proxy. This ensures secure, permissioned access to the Besu RPC endpoints.

---

Container Allocation with JWT Auth

Ali's Containers (Full Access)

VMID	Hostname	Role	Identity	IP Address	JWT Auth
1504	besu-sentry-5	Besu Sentry	N/A	192.168.11.154	✅ Required
2503	besu-rpc-4	Besu RPC	0x8a	192.168.11.253	✅ Required
2504	besu-rpc-4	Besu RPC	0x1	192.168.11.254	✅ Required
6201	firefly-2	Firefly	N/A	192.168.11.67	✅ Required

Access Level: Full root access to all containers

---

Luis's Containers (RPC-Only Access)

VMID	Hostname	Role	Identity	IP Address	JWT Auth
2505	besu-rpc-luis	Besu RPC	0x8a	192.168.11.255	✅ Required
2506	besu-rpc-luis	Besu RPC	0x1	192.168.11.202	✅ Required

Access Level: RPC-only access via JWT authentication

• No Proxmox console access
• No SSH access
• No key material access
• Access via reverse proxy / firewall-restricted RPC ports

---

Putu's Containers (RPC-Only Access)

VMID	Hostname	Role	Identity	IP Address	JWT Auth
2507	besu-rpc-putu	Besu RPC	0x8a	192.168.11.203	✅ Required
2508	besu-rpc-putu	Besu RPC	0x1	192.168.11.204	✅ Required

Access Level: RPC-only access via JWT authentication

• No Proxmox console access
• No SSH access
• No key material access
• Access via reverse proxy / firewall-restricted RPC ports

---

JWT Authentication Setup

Requirements

1. Nginx Reverse Proxy - All RPC containers must be behind nginx
2. JWT Validation - All requests must include valid JWT token
3. Identity Mapping - JWT tokens must map to permissioned identities (0x8a, 0x1)
4. Access Control - Different JWT tokens for different operators

Implementation

For Ali's Containers (2503, 2504)

• Full access JWT token
• Can access both 0x8a and 0x1 identities
• Admin-level permissions

For Luis's Containers (2505, 2506)

• RPC-only JWT token
• Can access 0x8a identity (2505)
• Can access 0x1 identity (2506)
• Limited to RPC endpoints only

For Putu's Containers (2507, 2508)

• RPC-only JWT token
• Can access 0x8a identity (2507)
• Can access 0x1 identity (2508)
• Limited to RPC endpoints only

---

Nginx Configuration

Example Configuration

Each RPC container should have nginx configuration with:

location / {
    auth_jwt "RPC Access" token=$cookie_auth_token;
    auth_jwt_key_file /etc/nginx/jwt/rs256.pub;
    
    proxy_pass http://192.168.11.XXX:8545;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

JWT Token Requirements

• Algorithm: RS256 (recommended) or HS256
• Claims: Must include operator identity and permissioned account
• Expiration: Set appropriate expiration times
• Validation: Validate on every request

---

Deployment Checklist

For Each RPC Container (2503-2508)

• Create LXC container
• Configure Besu with permissioned identity
• Set up nginx reverse proxy
• Configure JWT authentication
• Generate JWT tokens for operators
• Test JWT validation
• Configure firewall rules
• Disable discovery (prevents connection to Ethereum mainnet while reporting chainID 0x1 to MetaMask for wallet compatibility)
• Deploy static-nodes.json and permissioned-nodes.json

---

Security Considerations

1. Token Storage: JWT tokens should be stored securely
2. Token Rotation: Implement token rotation policy
3. Access Logging: Log all RPC access attempts
4. Rate Limiting: Implement rate limiting per operator
5. Network Isolation: Use firewall rules to restrict access

---

Related Documentation

• Missing Containers List
• ChainID 138 Configuration Guide
• Access Control Model
• Nginx JWT Auth – JWT setup and scripts

---

Last Updated: December 26, 2024
Status: ✅ Requirements Documented