ADR: JWT

Status

Accepted

Context

Game Y uses a microservices architecture (users-service and gameyapi). We need a secure, stateless way to share user identity across these services without forcing every API call to query a central database for session validation.

Decision

We will use JSON Web Tokens (JWT) for secure authentication.

• Flow: Upon login, the users-service generates a signed token containing userId and username.
• Secret Management: We use .env files for local development and GitHub Secrets for production to ensure the JWT_SECRET is never committed to version control.
• Validation: Consumer services (like gameyapi) extract and verify the token using a shared JWT_SECRET to identify the player.

Alternatives

• Session-based Authentication: Requires a centralized store (like Redis) to check session validity on every request. This introduces higher latency and a single point of failure.
• Opaque Tokens: The client receives a random string, but the resource server must still call the authentication service to "exchange" that string for user data, increasing network traffic.

Consequences

Positive

• Performance: Services verify users locally, reducing network latency and database load.
• Decoupling: The gameyapi does not need a direct connection to the user database to verify identity.
• Scalability: Stateless tokens make it easier to scale microservices horizontally.

Negative

• Security Risk: If the JWT_SECRET is compromised, an attacker can impersonate any user
• Revocation: Tokens remain valid until expiration (2 hours); there is no built-in way to "force logout" a specific token instantly.
• Payload Size: All necessary user data must fit in the token, which is sent with every request.

Verification

Verification is successful when a user logs in via users-service and the resulting token is successfully used by gameyapi to attribute a game session to the correct userId.