Skip to content

Proxy Configuration

Jump to bottom
Gabriele C. edited this page Jun 25, 2026 · 1 revision

Proxy Configuration

This page covers how to configure AuthMe behind a Velocity or BungeeCord proxy. Read the choosing a setup section first — the steps differ depending on whether your proxy runs in online-mode or offline-mode.

Table of Contents

Choosing a setup

The correct setup depends on two factors: which proxy software you use, and whether it runs in online-mode.

Your proxy online-mode in proxy config What you need
Velocity true Velocity — online-mode
Velocity false Velocity — offline-mode
BungeeCord / Waterfall online_mode: true BungeeCord — online-mode
BungeeCord / Waterfall online_mode: false BungeeCord — offline-mode

Note: The config key Hooks.bungeecord in AuthMe's config.yml is the universal proxy hook flag. Despite the name, it applies to both BungeeCord and Velocity setups.

Velocity

Velocity — online-mode proxy

Use this when online-mode = true in velocity.toml. Velocity authenticates players with Mojang directly and forwards the verified UUID to your backend servers. No extra proxy plugin is needed.

1. Install the correct AuthMe backend jar

Download the jar matching your backend server platform from the releases page and place it in the plugins/ folder of every backend server.

Server software Jar to use
Spigot 1.16 – 1.19 AuthMe-*-Spigot-Legacy.jar
Spigot 1.20 – 1.21 AuthMe-*-Spigot.jar
Paper 1.21+ AuthMe-*-Paper.jar
Folia 1.21+ AuthMe-*-Folia.jar

2. Configure each backend server

server.properties — the backend must be in offline-mode so Velocity handles authentication:

online-mode=false

spigot.yml — when using Velocity modern forwarding, BungeeCord legacy mode must be off:

settings:
  bungeecord: false

config/paper-global.yml (Paper 1.14+) — enable Velocity modern forwarding:

proxies:
  velocity:
    enabled: true
    online-mode: true        # must match your velocity.toml online-mode value
    secret: 'YOUR_FORWARDING_SECRET'   # copy from Velocity's forwarding.secret file

For Paper 1.14 – 1.18.2 these settings are in paper.yml under settings.velocity-support.enabled, settings.velocity-support.secret, and settings.velocity-support.online-mode instead.

plugins/AuthMe/config.yml — enable the proxy hook and optionally redirect players after login:

Hooks:
  bungeecord: true
  sendPlayerTo: 'lobby'     # optional: BungeeCord server name to send players to after login
 
DataSource:
  caching: false            # must be false in multi-server setups

Important: Hooks.bungeecord: true also requires the backend server to be in proxy mode. With Velocity modern forwarding, spigot.yml bungeecord stays false, but Paper's own proxies.velocity.enabled: true satisfies AuthMe's proxy-mode check on Paper servers. On Spigot (non-Paper) with modern forwarding, use legacy forwarding instead (player-info-forwarding-mode = "legacy" in velocity.toml) and set spigot.yml bungeecord: true.

3. Configure Velocity

velocity.toml:

online-mode = true
player-info-forwarding-mode = "modern"
 
[servers]
  auth  = "127.0.0.1:25566"
  lobby = "127.0.0.1:25567"
 
try = ["auth"]              # route new connections to the auth server first

The forwarding.secret file in your Velocity root directory contains the secret that must be copied verbatim into paper-global.yml on every backend.

4. Restart order

  1. Start all backend servers
  2. Start Velocity

Velocity — offline-mode proxy

Use this when online-mode = false in velocity.toml. AuthMe ships a dedicated authme-velocity proxy plugin that handles authentication state synchronisation between the proxy and your backend servers.

1. Install the correct AuthMe backend jar

Same as above — pick the jar matching your platform.

2. Install the authme-velocity proxy plugin

Download authme-velocity-*.jar from the same releases page and place it in your Velocity server's plugins/ folder.

3. Start both sides once, then stop everything

This generates the default config files on both the proxy and backend servers. Always refer to those generated files as the authoritative source for exact key names.

4. Configure the authme-velocity proxy plugin

Open the generated config in plugins/authme-velocity/ on your Velocity server. The key settings to adjust are:

# List the names of servers that have AuthMe installed.
# These must match the server names defined in velocity.toml.
authServers:
  - auth
 
# Server to send players to after successful login.
toServerAfterLogin: lobby
 
# Shared secret used to verify messages between the proxy plugin and AuthMe on the backend.
# Must be identical to Hooks.proxySharedSecret in every backend's AuthMe config.yml.
proxySharedSecret: 'change_this_to_a_long_random_string'

5. Configure each backend server

server.properties:

online-mode=false

spigot.yml — enable BungeeCord/proxy mode so AuthMe accepts the forwarded connection:

settings:
  bungeecord: true

plugins/AuthMe/config.yml:

Hooks:
  bungeecord: true
  sendPlayerTo: ''           # leave empty; the proxy plugin handles server switching
  proxySharedSecret: 'change_this_to_a_long_random_string'   # must match proxy plugin
 
DataSource:
  caching: false

Important: proxySharedSecret must be byte-for-byte identical on the proxy plugin and every backend server. A mismatch will silently prevent auto-login from working.

6. Configure Velocity

velocity.toml:

online-mode = false
player-info-forwarding-mode = "legacy"   # use "bungeeguard" for added security on shared hosting
 
[servers]
  auth  = "127.0.0.1:25566"
  lobby = "127.0.0.1:25567"
 
try = ["auth"]

7. Restart order

  1. Start all backend servers
  2. Start Velocity Players connect → land on the auth server → log in or register → the proxy plugin forwards them to toServerAfterLogin automatically.

BungeeCord

BungeeCord — online-mode proxy

Use this when online_mode: true in BungeeCord's config.yml. BungeeCord authenticates with Mojang and forwards the verified UUID. No extra proxy plugin is needed.

1. Install the correct AuthMe backend jar

Same platform table as above.

2. Configure each backend server

server.properties:

online-mode=false

spigot.yml:

settings:
  bungeecord: true

plugins/AuthMe/config.yml:

Hooks:
  bungeecord: true
  sendPlayerTo: 'lobby'     # optional
 
DataSource:
  caching: false

3. Configure BungeeCord

config.yml (BungeeCord root):

online_mode: true
ip_forward: true
 
servers:
  auth:
    address: 127.0.0.1:25566
    motd: '&1Auth server'
    restricted: false
  lobby:
    address: 127.0.0.1:25567
    motd: '&1Lobby'
    restricted: false
 
listeners:
  - priorities:
      - auth               # route new connections to the auth server first

4. Restart order

  1. Start all backend servers
  2. Start BungeeCord

BungeeCord — offline-mode proxy

Use this when online_mode: false in BungeeCord's config.yml. AuthMe ships a dedicated authme-bungee proxy plugin for this setup.

1. Install the correct AuthMe backend jar

Same platform table as above.

2. Install the authme-bungee proxy plugin

Download authme-bungee-*.jar from the releases page and place it in your BungeeCord server's plugins/ folder.

3. Start both sides once, then stop everything

This generates the default config files. Refer to the generated config as the authoritative source for exact key names.

4. Configure the authme-bungee proxy plugin

Open the generated config in plugins/authme-bungee/ on your BungeeCord server. The key settings to adjust are:

# List the names of servers that have AuthMe installed.
# Must match the server names in BungeeCord's config.yml.
authServers:
  - auth
 
# Server to send players to after successful login.
toServerAfterLogin: lobby
 
# Shared secret — must match Hooks.proxySharedSecret on every backend.
proxySharedSecret: 'change_this_to_a_long_random_string'

5. Configure each backend server

server.properties:

online-mode=false

spigot.yml:

settings:
  bungeecord: true

plugins/AuthMe/config.yml:

Hooks:
  bungeecord: true
  sendPlayerTo: ''
  proxySharedSecret: 'change_this_to_a_long_random_string'   # must match proxy plugin
 
DataSource:
  caching: false

6. Configure BungeeCord

config.yml:

online_mode: false
ip_forward: true
 
servers:
  auth:
    address: 127.0.0.1:25566
    motd: '&1Auth server'
    restricted: false
  lobby:
    address: 127.0.0.1:25567
    motd: '&1Lobby'
    restricted: false
 
listeners:
  - priorities:
      - auth

Security note: Running BungeeCord in offline-mode without firewalling exposes your backend servers to direct connections that bypass authentication entirely. Firewall your backend ports so only the proxy IP can reach them. On shared hosting where firewalling isn't possible, use player-info-forwarding-mode = "bungeeguard" in Velocity, or install BungeeGuard for BungeeCord.

7. Restart order

  1. Start all backend servers
  2. Start BungeeCord

Shared backend settings

These settings in plugins/AuthMe/config.yml are relevant to every proxy setup:

Hooks:
  # Required for every proxy setup, including Velocity. Default: false.
  bungeecord: true
  # BungeeCord server name to send players to after login. Leave empty to disable.
  # Do not set this when using the authme-velocity or authme-bungee proxy plugin —
  # those plugins handle server switching themselves via toServerAfterLogin.
  sendPlayerTo: ''
  # Shared secret for verifying perform.login messages from the AuthMe proxy plugin.
  # Required only for offline-mode setups using authme-velocity or authme-bungee.
  # Must match the proxySharedSecret value in the proxy plugin config.
  proxySharedSecret: ''
 
DataSource:
  # Disable the database cache in any multi-server or proxy environment. Default: true.
  caching: false

Why Hooks.bungeecord even for Velocity?

Hooks.bungeecord is AuthMe's single unified flag for any proxy type. The name is a legacy holdover — it enables proxy-mode behaviour (trusted UUID forwarding, plugin messaging) regardless of whether your proxy is BungeeCord or Velocity.

AuthMe validates on startup that the backend server is actually running in a proxy-compatible mode:

  • Spigot + legacy forwarding: spigot.yml bungeecord: true → check passes.
  • Paper + Velocity modern forwarding: proxies.velocity.enabled: true in paper-global.yml → check passes even though spigot.yml bungeecord remains false.
  • Neither configured: AuthMe logs a warning and auto-disables the hook to prevent untrusted payload attacks.

Common issues

[AuthMe] BungeeCord hook will be automatically disabled!

Your backend is not in proxy mode. For Velocity modern forwarding confirm proxies.velocity.enabled: true is set in config/paper-global.yml. For legacy forwarding confirm settings.bungeecord: true is set in spigot.yml. See the relevant setup section above.

Players can move and execute commands before logging in

AuthMe's movement and command restrictions are enforced on the backend server. Confirm Hooks.bungeecord: true is set and that the backend proxy-mode check passes (see above).

Players are not forwarded to lobby after login

  • For online-mode setups (no proxy plugin): set Hooks.sendPlayerTo: 'lobby' in config.yml.
  • For offline-mode setups (with proxy plugin): set toServerAfterLogin: lobby in the proxy plugin config and leave Hooks.sendPlayerTo empty. Setting both simultaneously causes a conflict. Auto-login does not work across servers

DataSource.caching must be false on every backend. With caching on, each server maintains its own local login state and cannot observe logins that happened on a different server.

proxySharedSecret mismatch

The secret in the proxy plugin config and in every backend config.yml must be identical, including case and whitespace. Regenerate a fresh random string, paste it into both locations, and restart all affected servers.

Players have to log in again when switching to a non-auth server

The proxy plugin (authme-velocity or authme-bungee) must be running on the proxy. If only the backend plugin is installed without the proxy-side plugin, login state is not forwarded and players will be prompted again on every server switch.

See also: Releases

Clone this wiki locally