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
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
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
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:
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
Pros
Cons
Random session tokens (current)
Format
Stored in a sessions table and tied to the account.
Pros
Cons
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.
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:
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