Premium Auto-Login

How It Works

Premium auto-login lets Mojang-authenticated players skip /login entirely. Their identity is verified cryptographically — no password needed.

There are two modes depending on your server setup:

Standalone (no proxy)

XLogin injects a handler into the server's Netty pipeline that intercepts login packets:

  1. Player connects (offline-mode server).
  2. XLogin intercepts the LoginStart packet.
  3. Checks if the player should be verified (database flag or Mojang API).
  4. If premium: sends an EncryptionRequest with an RSA public key.
  5. Client authenticates with Mojang and responds with EncryptionResponse.
  6. XLogin decrypts the shared secret, enables AES/CFB8 encryption.
  7. Verifies with Mojang's hasJoined session server.
  8. If verified: stores UUID + textures, player joins and is auto-logged.

Behind a proxy (Velocity / BungeeCord)

The Netty injection cannot be used behind a proxy — the proxy would interpret it as online-mode. XLogin on the proxy handles verification directly:

  1. Player connects to the proxy.
  2. XLogin checks the database for premium=1 (or Mojang API in strict mode).
  3. If premium: forces online-mode, proxy does Mojang handshake.
  4. Verified profile sent to backend via Redis (instant) + plugin messaging (fallback).
  5. Player is routed directly to lobby (skips auth server entirely).

See the Proxy Setup guide for detailed installation instructions.

Strict Mode vs Opt-In Mode

ModeConfigBehavior
STRICTpremium.mode: "strict"Any Mojang username is forced through verification. Cracked players cannot use a premium name. /premium and /unpremium commands are disabled. Best for maximum security.
OPT-INpremium.mode: "opt-in"Only players who used /premium are verified. Everyone /registers first, then can opt-in. /premium and /unpremium commands available. Best for mixed servers.

UUID Modes

ModeConfigBehavior
OFFLINEpremium.uuid-mode: "OFFLINE"All players use offline UUIDs. Simple and safe. Default.
REALpremium.uuid-mode: "REAL"Premium players get their real Mojang UUID. Enables cosmetics on Lunar/Badlion. Cracked players still use offline UUIDs.

Changing premium.uuid-mode after players have data is destructive. Premium players' UUIDs will change, orphaning their data. Set this once at server setup.

Username Change Migration

When a premium player changes their Mojang username, their offline UUID changes. XLogin detects this automatically:

  1. Player connects with their new username.
  2. Mojang handshake verifies — same Mojang UUID as before.
  3. XLogin finds the old account via mojang_uuid column.
  4. Migrates player_uuid in accounts, sessions, and 2FA tables.
  5. Publishes a MIGRATE sync event across the network.

No data is lost — password, premium flag, 2FA, email, sessions are all preserved.

This only applies in premium.uuid-mode: "OFFLINE". In REAL mode, the Mojang UUID is used directly, so username changes don't affect the UUID.

AuthenticationTwo-Factor Authentication