Velocity and Paper: Check That Players Cannot Bypass Your Proxy
Before opening a Velocity and Paper network, verify two things separately: players can join through the proxy with the correct identity, and an untrusted network cannot connect directly to the game servers. Modern forwarding adds a check on the origin of forwarded player information, but it does not replace a firewall. Velocity's server security guide recommends combining these protections.
This is an acceptance test plan for community owners preparing an authenticated Java network. A backend means a Paper game server behind the proxy, such as a lobby or survival server. The scope is current Paper with Velocity modern forwarding. Networks supporting older clients, Floodgate or modded servers also need their own compatibility and identity review. We have not run these tests on your infrastructure.
Write down the route you intend to release
Create a short deployment sheet listing the public entry point, each backend and port, the addresses the proxy uses to reach them, and the owner of each network rule. Include any additional public addresses on those machines. A convenient player-facing hostname does not establish that other routes are closed.
Consider an example with one proxy, one lobby and one survival server. Release requires both intended journeys to work: joining the lobby and moving to survival. Seeing the network in the multiplayer list is insufficient.
Add the following to the sheet:
- Velocity and Paper builds, plus versions of plugins involved in access or permissions.
- A test owner and a person responsible for releasing the network; one person may hold both roles.
- A test account with known inventory and permissions, without unnecessary administrative privileges.
- A procedure for restoring the previous configuration while keeping public access closed.
When commissioning managed infrastructure, use this sheet to agree which routes the technical team must verify and what evidence it will hand over.
Choose isolation that fits the deployment
Velocity documents listening on 127.0.0.1 when the proxy and backends share a trusted machine, and encrypted tunnels between machines. Distributed deployments also require network rules to stay aligned with the authorized proxies. Read the isolation options before applying a configuration recipe.
Turn the chosen design into an observable condition: “the survival port accepts connections only through the authorized route.” Ask the administrator to document how this is enforced, including provider rules and any published container ports. Sharing a physical host does not make a localhost recipe valid for every architecture.
Do not temporarily expose a backend to the entire internet to troubleshoot a proxy connection. Keep the restriction in place and check addresses, port, listening interface and routing from the authorized source first. Test only systems you own or have permission to assess.
Check authentication without mixing up three settings
In this article's design, online-mode = true in velocity.toml makes the proxy authenticate players. The same file sets player-info-forwarding-mode = "modern" and identifies the secret file through forwarding-secret-file. These options are documented in the Velocity configuration reference.
On each backend, the official modern forwarding instructions specify online-mode=false in server.properties and settings.bungeecord: false in spigot.yml. The backend delegates authentication to the proxy; this step belongs within the protected design you are verifying.
Review these existing keys in config/paper-global.yml, without replacing the whole file:
| Key | Required condition for this design |
|---|---|
proxies.velocity.enabled | true |
proxies.velocity.online-mode | true, matching the proxy |
proxies.velocity.secret | Matches the secret configured in Velocity |
The Paper global configuration reference explains the relationship to player data and UUID handling. Check the UUID, the player's identifier, as well as the visible name. Do not confuse proxies.velocity.online-mode with online-mode in server.properties: this design deliberately gives them different values for different purposes.
Compare secrets through a private administrative channel. Put only “matches” or “does not match” in the report, never the value itself. Keep secrets out of screenshots, tickets and repositories. Restart the affected components during the maintenance window and verify the applied configuration again.
Run a small acceptance matrix
Prepare two test locations: one outside the authorized networks and one along the proxy's permitted route. Record the time, source, destination and observed outcome. The table describes expected outcomes; it does not report completed measurements.
| Test | Outcome required to proceed |
|---|---|
| Legitimate connection through the proxy | The account reaches the lobby and then survival |
| Identity check on each backend | UUID, inventory and permissions match expectations for that account and server |
| Direct external TCP connection to every backend port | No connection is established |
| Access along the authorized route | The proxy reaches each intended backend |
| Restart and repeat | Allowed routes still work and blocked routes remain blocked |
The negative network test asks more than “Minecraft kicked me.” If TCP connects and the game subsequently rejects the client, you observed an application rejection; you have not yet demonstrated the agreed network isolation. Conversely, do not treat a single timeout as complete proof. Confirm the destination and establish that the backend works using the corresponding positive test.
In an isolated rehearsal environment, you can add a secret-validation test. Use an authorized test proxy with a deliberately different secret, verify that joining fails, then repeat with the correct value. Do not change the production secret or open production ports for this exercise. Record the outcome alone.
Use failures to make a release decision
If the lobby works but survival does not, compare their routes and configurations. That comparison narrows the investigation; it does not prove which setting is wrong. If an account has an empty inventory or an unexpected rank, stop the release and investigate identity and associated data before creating new profiles or moving player files.
A direct route that remains open is an unresolved item even if modern forwarding rejects the login. If behaviour changes after a restart, check which configuration the running process actually loads and who owns persistent network rules. Retain the earlier report, repeat affected tests and include a complete legitimate connection journey.
The handover should contain the completed matrix, software versions, responsible people, unresolved issues and triggers for retesting. Adding a backend, moving hosts or changing authentication requires reviewing the route again. This exercise does not certify capacity, DDoS protection or the absence of plugin defects.
For custom code involved in access, permissions or identity, include these checks in the scope of your Minecraft development project. Mineando handles paid projects with an individually agreed scope; ongoing support is arranged separately.
