Configuration

# Session timeout in minutes (0 = login every time)
session-timeout: 30

# Maximum login attempts before kick
max-login-attempts: 5

# Time in seconds to login after joining (0 = unlimited)
login-timeout: 60

# Password length limits
min-password-length: 6
max-password-length: 32

# Require uppercase + lowercase + number
require-strong-password: false

# Maximum accounts per IP (0 = unlimited)
max-accounts-per-ip: 3

# Allow new registrations
allow-registration: true

# Kick unregistered players who don't register within timeout
force-registration: true

# Show last login date and IP after authentication
show-last-login: true

While unauthenticated, players are restricted from all actions:

# Hide player from others until logged in
hide-unlogged-players: true

# Prevent movement before login (allows head rotation)
block-movement: true

# Prevent all interactions before login
block-interactions: true

# Hide quit message if player disconnects without authenticating
hide-quit-if-not-logged: true

# Commands allowed before login
allowed-commands:
  - "/help"

# Teleport player to a fixed spawn on join
teleport-to-spawn: false

# Only allow login from the last known IP
ip-lock: false

# Temporary IP ban and rate limiting
security:
  ip-ban-duration: 30           # minutes
  ip-rate-limit-max: 10         # max failed attempts
  ip-rate-limit-window: 10      # time window in minutes

# Notify admins on failed login
notify-on-failed-login: true

# Log all login/register events
log-events: true

# Name validation
name-validation:
  enabled: true
  pattern: "^[a-zA-Z0-9_]{3,16}$"
  blocked-words:
    - "admin"
    - "moderator"
    - "server"
    - "console"

XLogin implements per-player online-mode by injecting a custom handler into the server's Netty pipeline.

# Enable premium auto-login
premium-auto-login: false

# Strict mode: force encryption for all premium usernames
# Opt-in mode: only verify players who used /premium
premium-strict-mode: true

# UUID mode: OFFLINE or REAL
# OFFLINE = all players use offline UUIDs (default, safe)
# REAL = premium players get their Mojang UUID (enables cosmetics on Lunar/Badlion)
uuid-mode: OFFLINE

How It Works

1. Player connects to the server (offline-mode).
2. XLogin's Netty handler intercepts the LoginStart packet.
3. Checks if the player's name is a premium Mojang account.
4. If premium: sends an EncryptionRequest to the client.
5. The client authenticates with Mojang and responds with EncryptionResponse.
6. XLogin verifies with Mojang's hasJoined session server endpoint.
7. If verified: stores the player's Mojang UUID and skin textures, authenticates instantly.

Security

• Name stealing protection (strict mode) — Cracked players using a premium username cannot complete the Mojang handshake and are disconnected.
• Encryption — The connection is encrypted with AES/CFB8 after the handshake, same as vanilla online-mode.
• Existing accounts — Players who already registered as cracked can opt-in with /premium.

Strict Mode vs Opt-In Mode

The premium-strict-mode setting controls how premium detection works for new players:

UUID Modes

The uuid-mode setting controls how UUIDs are assigned to premium players:

Warning: Changing uuid-mode after players have data is destructive. Premium players' UUIDs will change, orphaning their data in other plugins. This is a "set once at server setup" decision.

Username Change Auto-Migration

When a premium player changes their Minecraft username on Mojang, their offline UUID changes. XLogin detects this and automatically migrates their account:

1. Player connects with their new username.
2. Netty handshake verifies with Mojang — same Mojang UUID as before.
3. XLogin finds the old account with the same mojang_uuid but a different offline UUID.
4. Automatic migration: updates player_uuid in xlogin_accounts, xlogin_sessions, and xlogin_2fa in a single transaction.
5. Player keeps their password, premium flag, 2FA, email, and sessions.

This feature only applies in uuid-mode: OFFLINE. In REAL mode, the Mojang UUID is used directly, so a username change doesn't affect the UUID.

two-factor:
  enabled: false

XLogin supports TOTP (Time-based One-Time Password), compatible with Google Authenticator, Authy, and Microsoft Authenticator.

Setup for Players

1. Admin enables it in config: two-factor.enabled: true
2. Player runs /2fa setup — they receive a secret key.
3. Player adds the key to their authenticator app.
4. Player runs /2fa <code> with the 6-digit code to confirm.
5. On future logins, after /login, the player must also enter /2fa <code>.

# Title/subtitle shown on join
login-title:
  enabled: true
  login-title: "<gold><bold>Welcome back!"
  login-subtitle: "<gray>Use <white>/login <password>"
  register-title: "<gold><bold>Welcome!"
  register-subtitle: "<gray>Use <white>/register <password> <password>"

# Boss bar countdown
login-bossbar:
  enabled: true
  text: "<red>Please authenticate - {time}s remaining"
  color: RED

# Action bar reminder
login-actionbar:
  enabled: true
  login-text: "<yellow>... Use /login <password> ..."
  register-text: "<yellow>... Use /register <password> <password> ..."

All messages support MiniMessage formatting.

Players can link an email to their account and use it to recover their password if forgotten.

email-recovery:
  enabled: false
  smtp:
    host: "smtp.gmail.com"
    port: 587
    username: ""
    password: ""
    from: "noreply@example.com"
    tls: true
  code-expiry: 10  # minutes
  cooldown: 5      # minutes between requests

How It Works

1. Player forgets their password.
2. Runs /recover <username> — XLogin sends a 6-digit code to their linked email.
3. Player enters /recover <username> <code> <newpassword> — password is reset.
4. Player can now /login with the new password.

Recovery codes are stored in memory and expire after code-expiry minutes. A cooldown prevents spam.

bedrock:
  # Auto-login Bedrock players (authenticated via Xbox Live)
  auto-login: true