🔐 FireMUD System Architecture: Authentication & Authorization

This document describes how FireMUD authenticates clients, issues internal JWTs, manages session state, and enforces role-based access across services.

Authentication is performed via plaintext LOGIN commands. Clients are stateless; session state is managed server-side in Redis and restored via the Game Session Service.

🔁 Login and Session Flow

All clients — whether connecting via Telnet or WebSocket — must authenticate using the LOGIN command:

• LOGIN → Starts prompt-based login (username → password)
• LOGIN <username> <password> → Attempts immediate login
• LOGON → Alias for LOGIN

Clients must re-authenticate only after disconnecting (TCP or WebSocket loss). If a valid Redis session exists (accountId + playerId), the Game Session Service resumes gameplay seamlessly.

🔗 For session resumption and reconnect edge cases, see Reconnection Strategy

👥 Multi-Client Behavior and Session Takeover

Each character can only be controlled by one session at a time.

If a new login is received for the same playerId:

• The existing session is terminated
• The Redis session is rebound to the new socket
• Tick state, command queues, and timers are preserved

This enables:

• Clean device handoff
• Forced logins (e.g., “kick and take over”)
• Seamless resumption without gameplay loss

🔒 All session rebinding is enforced by the Game Session Service using Redis locks. 🔗 See Redis Session Keys

🧾 JWT Format and Role Claims

Internal JWTs are issued by the Account Service and used for backend gRPC authorization. Gameplay clients never store or transmit tokens. Admin UIs may supply JWTs for optional validation at the Spring Cloud Gateway.

🧠 Claims

🧾 Example JWT Payload

• accountId: "user-123"
• globalRoles: ["moderator"]
• scopedRoles:
  • "game-abc" → ["admin", "designer"]
  • "game-def" → ["moderator"]

Tokens are short-lived and internal only. Gameplay context (e.g., playerId, worldId) is stored in Redis and sent via command envelopes.

👮 Role-Based Authorization

Access to services is governed by roles from the JWT:

JWT Usage Scope

• ✅ Meta/control services (e.g. Game Design, Admin, Account) validate JWTs to authorize access
• 🚫 Gameplay services (e.g. Game Logic, Entity, World) do not validate JWTs — they rely on the Game Session Service to enforce access

🔄 Mid-Session Role Updates

If roles change during an active session (e.g., a player is promoted to admin):

1. The Game Session Service detects or requests a role refresh
2. It contacts the Account Service to obtain a new JWT
3. Updated claims are injected into subsequent gRPC calls

✅ This process is invisible to the client — no re-login is needed.

🧠 Session and Identity Management

The Game Session Service is responsible for:

• Authenticating sockets and binding identity context
• Managing Redis session state (e.g. playerId, worldId, tick region)
• Managing JWTs for backend interactions

🔗 See Session Keys and Gameplay Binding for Redis structure and gameplay rebinding.

✅ Summary

📚 Related Documentation

• Reconnection Strategy
• Tick System and Runtime Design
• Redis Architecture