Skip to main content

​
Online Mode

Online mode determines how Gate authenticates players connecting to your network. This is one of the most critical security settings for your Minecraft proxy.

​
What is Online Mode?

Online mode controls whether Gate verifies player identities with Mojang’s authentication servers:
  • Online Mode (Enabled): Gate authenticates every player with Mojang’s session servers, ensuring that only legitimate Minecraft account holders can connect.
  • Offline Mode (Disabled): Gate skips authentication, allowing anyone to connect with any username. This is not recommended for production servers.
Gate defaults to online mode enabled (onlineMode: true) for security reasons.

​
Configuration

The online mode setting is configured in your config.yml: 
config:
  # Whether to use the proxy in online (authenticate players with Mojang API) or offline mode (not recommended).
  onlineMode: true

config:
  onlineMode: true
When online mode is enabled:
  1. Player connects to Gate
  2. Gate generates an authentication challenge
  3. Player’s client contacts Mojang’s session servers
  4. Gate verifies the response with Mojang
  5. Upon successful verification, player is authenticated
Benefits:
  • Prevents username spoofing
  • Ensures only legitimate Minecraft account holders can join
  • Protects against unauthorized access
  • Maintains consistent player UUIDs across servers

​
Offline Mode

config:
  onlineMode: false
Offline mode disables Mojang authentication. Players can join with any username, making your server vulnerable to impersonation attacks.
When offline mode is enabled:
  • No authentication with Mojang servers
  • Players can choose any username
  • UUIDs are generated based on username (not account)
  • Anyone can impersonate admins or other players
Use cases for offline mode:
  • Local testing and development
  • Private LAN networks
  • Offline gameplay environments
  • Testing with cracked clients (use with extreme caution)

​
Authentication Flow

Gate uses RSA encryption and secure authentication flows to verify players:
  1. Connection Establishment: Player initiates connection to Gate
  2. Encryption Request: Gate sends public key to client
  3. Encryption Response: Client encrypts shared secret with public key
  4. Session Verification: Gate verifies session with Mojang’s API at https://sessionserver.mojang.com/session/minecraft/hasJoined
  5. Authentication Success: Player is granted access with verified UUID
The authentication flow uses AES-CFB8 encryption to secure the connection after the initial handshake.

​
Custom Authentication Servers

You can customize the Mojang session server URL for alternative authentication providers: 
config:
  auth:
    # Customize the base URL for the Mojang session server
    # Defaults to https://sessionserver.mojang.com/session/minecraft/hasJoined
    sessionServerUrl: https://example.com/mitm/session/minecraft/hasJoined
This is useful for:
  • Using alternative authentication services
  • Implementing custom authentication logic
  • Testing authentication flows in development
Only use trusted authentication servers. Malicious authentication servers can compromise your network security.

​
Online Mode with Existing Players

Gate provides a setting to handle conflicts when premium players join: 
config:
  # Whether to kick existing connected player when an online-mode player with the same name joins.
  onlineModeKickExistingPlayers: false
When set to true:
  • A premium account holder can join and disconnect the cracked player using their name
  • Useful for servers transitioning from offline to online mode
  • Helps enforce legitimate account usage
Enabling this setting allows premium players to potentially “bully” offline players by repeatedly joining and kicking them. Use with caution.

​
Backend Server Configuration

When Gate is in online mode, your backend servers should be configured appropriately: Backend servers should run in offline mode because Gate handles authentication: Spigot/Paper (server.properties): 
online-mode=false
Velocity/BungeeCord (backend servers): 
online-mode=false
Gate authenticates players, then forwards their verified information to backend servers using a forwarding mode. This is why backend servers can safely run in offline mode.

​
Why Backend Servers Should Be Offline

  1. Avoid Double Authentication: Gate already authenticated the player
  2. Faster Connections: No redundant Mojang API calls
  3. Consistent Player Data: Gate manages the authenticated session
  4. Proper Forwarding: Player info (UUID, IP) is forwarded securely
See Forwarding Modes for how to securely forward player information to backend servers.

​
Security Best Practices

​
For Production Servers

Always use online mode for production servers accessible from the internet.
  1. Enable online mode: onlineMode: true
  2. Use modern forwarding: Configure Velocity forwarding with a secret
  3. Protect backend servers: Configure firewalls to only accept connections from Gate
  4. Enable rate limiting: Protect against brute-force authentication attempts
  5. Monitor authentication: Enable logging for authentication events

​
For Development Environments

config:
  # Safe for local development only
  onlineMode: false
  forwarding:
    mode: none
Offline mode is acceptable for local development, but never deploy offline mode to production.

​
Rate Limiting Authentication

Gate includes built-in rate limiting for login attempts: 
config:
  quota:
    # Limit how many login requests can be made by the same IP range
    logins:
      enabled: true
      burst: 3        # Maximum login attempts
      ops: 0.4        # 0.4 logins per second (1 every 2.5 seconds)
      maxEntries: 1000
This protects against:
  • Brute-force authentication attacks
  • Excessive Mojang API requests
  • Denial of service through authentication spam

​
Troubleshooting

​
Players Can’t Connect (Online Mode)

Symptoms: “Failed to verify username” or “Invalid session” Solutions:
  1. Verify Mojang services are online: https://status.mojang.com/
  2. Check firewall allows outbound HTTPS to Mojang
  3. Ensure players are using legitimate Minecraft accounts
  4. Verify sessionServerUrl is correct if customized

​
Players Can Impersonate Others

Cause: Offline mode is enabled Solution: Enable online mode: 
config:
  onlineMode: true

​
Backend Server Authentication Errors

Cause: Backend server is in online mode while Gate is forwarding Solution: Set backend servers to offline mode: 
# server.properties
online-mode=false
Then configure proper forwarding mode.

​
Migration Guide

​
Migrating from Offline to Online Mode

Migrating from offline to online mode will change player UUIDs, causing players to lose their data (inventory, homes, permissions, etc.).
Steps:
  1. Backup everything: Player data, worlds, databases
  2. Enable online mode: 
    config:
  onlineMode: true
  3. Convert player data: Use a UUID migration plugin like:
  4. Update permissions: Reconfigure permissions with new UUIDs
  5. Test thoroughly: Verify all player data migrated correctly
  6. Communicate: Inform players about the change
Consider enabling onlineModeKickExistingPlayers: true during migration to help enforce legitimate accounts.

Build docs developers (and LLMs) love

Get started for freeTalk to us