-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Description
Historically, session tokens were derived directly from user credentials (email, password, optionally 2FA token), but TFS has recently (#4706) transitioned to randomly-generated base64-encoded token stored in the database. However, this change has introduced compatibility issues with existing AACs (such as MyAAC), which rely on the previous credential-based scheme.
Background
The Forgotten Server has evolved significantly in its handling of account authentication. Previously, the session token provided to the client was simply a concatenation of credentials (see below).
This method was simple and easily interoperable with AACs and third-party tools, allowing for stateless verification on the server side.
In newer versions, TFS now issues a randomly-generated token, which is:
- Base64-encoded
- Stored in the database upon generation
- Used as a true bearer token for session continuity
This change was motivated by security concerns with the previous approach, but it has broken compatibility with existing account management websites and tooling.
See #4945 for initial discussion.
Comparison of Token Formats
Plaintext credential tokens (legacy)
Format
email\npassword[\n2FA]
Pros
- Stateless: requires no server-side session persistence
- Easy to implement: AACs and client tools can generate this format with minimal logic
- Portable: Can be easily reused across tools that know the user credentials
Cons
- Vulnerable to replay attacks
- Encourages storing plaintext credentials on clients
- No expiration or revocation mechanism: the token is valid as long as the credentials remain unchanged and 2FA token remains valid (probably lenghtened from 1 minute for session purposes)
Random session tokens (current)
Format
base64(random_bytes(16))
Stored in a sessions table and tied to the account.
Pros
- Can be rotated and invalidated at any time
- Resistant to replay attacks and session hijacking
- Flexible: can store metadata like expiration and IP
Cons
- Requires state: server must store and validate tokens
- Breaks compatibility with current AACs expecting a credentials-based token
- More complex implementation, especially for third-party tools, requiring access to the database
Problem
While the new session token mechanism theoretically improves security, its incompatibility with existing AACs causes usability issues for a large portion of the community. Without official support or clear documentation on the token format and usage, users are forced to modify AACs or downgrade to insecure practices.
There is a need for a well-documented, interoperable session token format that balances security with ease of integration.
Proposed solutions
Option A: Hybrid Token Scheme
Introduce a transitional token format where AACs can optionally request a session token by submitting credentials (via HTTPS) to a /token endpoint, which returns a proper random token.
- AACs don’t generate the token manually
- Server maintains secure session tokens
- Compatibility layer preserves existing AAC workflows
This may require additional steps to make sure the token endpoint is not publicly exposed and only accessible from the AAC.
Option B: Signed Tokens (JWT-like)
Move toward signed tokens (e.g., JWT or custom HMAC-signed tokens) that are:
- Stateless
- Time-limited
- Include account ID and metadata
- Signed using a server-side secret
This maintains security while reducing session storage needs. However, it may be limited by the client's maximum token length.
Option C: compatibility layer
Implement a server-side compatibility layer that detects credential-based tokens, logging a deprecation warning. Support both schemas for a transitioning period (MUST define a deadline) and then fully migrate to a new schema.
Option D: server-handled tokens
Let TFS create and validate the tokens, expose an endpoint in the HTTP server that creates a session token with user and password, therefore AAC does not need to handle game sessions at all and can just relay the token to the client.
Recommendation
To be defined