Skip to content

Draft: Session Token Format #4963

@ranisalt

Description

@ranisalt

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions