Skip to content

Modern Forwarding

Jump to bottom
Fed43 edited this page Oct 10, 2026 · 1 revision

Modern Forwarding

Modern forwarding is the mechanism MineAlphaProxy uses to pass player information (real IP, UUID, skin) to backend servers. This page explains what it is, how to set it up, and how to debug common problems.

What Is Modern Forwarding

Without forwarding, a backend server sees only the proxy's IP address and treats every player as connecting from 127.0.0.1. The player's real IP, UUID, and skin are lost.

With modern forwarding, the proxy packages the player's real data into a signed token and sends it to the backend during login. The backend unpacks it, verifies the signature, and uses the real player data.

Modes Comparison

Mode Protocol Works with Status
none - Any backend No forwarding at all
legacy BungeeCord ip_forward 1.12 and lower Supported
modern Velocity native 1.13+ Recommended

For modern Paper/Spigot servers (1.13+), always use modern.

Server Setup

Step 1. Configure MineAlphaProxy

In core.yml:

forwarding:
  mode: "modern"
  secret-file: "forwarding.secret"

On the next launch, if forwarding.secret does not exist, MineAlphaProxy creates one automatically:

[..] INFO - Generated new forwarding.secret: forwarding.secret
[..] WARN - Make sure backend servers use the same secret for modern forwarding!

Step 2. Get the Secret

Open forwarding.secret in a text editor. It contains a single line - a 32-character hex string:

a3f8c91d64e2b7f01284d5c9e7b1a034

Copy this value.

Step 3. Configure the Backend Server

For Paper 1.19+, edit config/paper-global.yml:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "a3f8c91d64e2b7f01284d5c9e7b1a034"

For Paper 1.16 - 1.18, edit paper.yml:

velocity-support:
  enabled: true
  online-mode: true
  secret: "a3f8c91d64e2b7f01284d5c9e7b1a034"

For Spigot (1.13+), edit spigot.yml:

settings:
  bungeecord: false

And in server.properties:

online-mode=false

Important: online-mode in paper-global.yml under proxies.velocity is not the same as server.properties.online-mode:

Setting Meaning
paper-global.yml → proxies.velocity.online-mode: true Trust the UUID sent by the proxy
server.properties → online-mode=false Do not verify clients with Mojang

Both should be set as shown above.

Step 4. Restart Everything

  1. Stop the backend server (stop in console)
  2. Stop MineAlphaProxy
  3. Start MineAlphaProxy first
  4. Start the backend
  5. Connect a player

Verifying It Works

After a player successfully joins, the proxy log should show:

[..] INFO - Login Start: Steve from 203.0.113.45 (extra 16 bytes, uuid 069a79f4-...)
[..] INFO - Connecting to backend 'lobby' (127.0.0.1:25566)...
[..] INFO - Backend 'lobby' reached
[..] INFO - Backend login plugin request: channel='velocity:player_info'
[..] INFO - Sending modern forwarding data for Steve (uuid 069a79f4-...)
[..] INFO - Compression enabled (threshold=256)
[..] INFO - Login Success rewritten with UUID 069a79f4-...

The backend should log:

[..] INFO - UUID of player Steve is 069a79f4-44e9-4726-a5be-fca90e38aaf5
[..] INFO - Steve[/203.0.113.45:xxxxx] logged in

If the backend shows 127.0.0.1 instead of the real IP, forwarding is not working.

Common Problems

"Unable to verify player details"

The client received a Login Success packet with a UUID that does not match what it sent. Common causes:

  1. paper-global.yml → proxies.velocity.online-mode: false Fix: change to true. The backend must trust the UUID from the proxy.

  2. Client running a different version than the backend Fix: enable ViaProxy so all client versions are accepted.

  3. Wrong forwarding format This was fixed in MineAlphaProxy 1.0.1-ALPHA. Make sure you are on that version or newer.

"Backend requested encryption"

The proxy is talking to a backend that expects direct encryption - this happens when proxies.velocity.enabled: false on the backend.

Fix: set proxies.velocity.enabled: true and restart the backend.

Player UUID changes every join

The secret does not match between proxy and backend.

Fix:

# On the proxy
cat forwarding.secret

# On the backend (paper-global.yml)
# Compare the "secret:" value character by character

They must be identical. After fixing, restart both sides.

Player IP is 127.0.0.1 on the backend

Modern forwarding is disabled or misconfigured.

Check:

  • paper-global.yml → proxies.velocity.enabled: true
  • paper-global.yml → proxies.velocity.online-mode: true
  • Restart the backend (not /reload)

"This server is not configured to accept proxy connections"

The backend has bungeecord: true in spigot.yml, which conflicts with modern forwarding.

Fix:

# spigot.yml
settings:
  bungeecord: false

Premium vs Cracked Clients

Modern forwarding works for both:

  • Premium clients send their real Mojang UUID
  • Cracked clients send a UUID generated from their username

MineAlphaProxy passes whichever UUID the client sent. The backend uses that UUID for permission lookups, player data, etc.

Recommendation: for cracked players, use an authentication plugin (SimpleLogin, SecureProxy, etc.) so they cannot impersonate premium users.

Secret Rotation

To rotate the forwarding secret:

  1. Stop MineAlphaProxy
  2. Delete forwarding.secret
  3. Stop all backends
  4. Start MineAlphaProxy - it will generate a new secret
  5. Copy the new secret to every backend's paper-global.yml
  6. Start backends

Every player will be treated as new. Back up player data before rotating.

Security Notes

  • The secret is a shared key - never publish it, never commit it to Git
  • .gitignore in the MineAlphaProxy repository already excludes forwarding.secret
  • If the secret leaks, rotate it immediately
  • Restrict filesystem access to forwarding.secret - only the proxy process should read it

Next Steps

Clone this wiki locally