AuthCore Server Admin Guide

A step-by-step guide for server owners, from first install to a fully secured server. AuthCore is an authentication framework for offline/cracked servers: it forces every player to register with a password and log in before they can play, with 2FA/MFA, a web admin panel, a honeypot, anti-bot protection and network-wide single sign-on.

✨ AuthCore runs out of the box with zero configuration (SQLite database, no Redis, no email). Every database and service below is optional, enable only what you need.

🧩 The same jar is your server mod and your BungeeCord/Velocity proxy plugin, install it once wherever AuthCore should run.

What you'll learn here

1. Pick the right jar

AuthCore ships range jars, one jar covers a whole Minecraft version range. Pick the row matching your server's Minecraft version AND loader:

💡 Which loader? Use the loader your server already runs, every range ships all supported loaders. Fabric needs Fabric API installed alongside the jar; Forge and NeoForge need nothing extra. All three drop the jar into mods/.

Download from: Modrinth or GitHub Releases.

🧠 Newbie question: "why are there so many jars?", Because Minecraft changed its code format at 26.1, one jar cannot work on every version. Each range jar is tested on every version of its range before release. More background: docs/26x.md.

2. Install

1. Download the jar that matches your Minecraft version and loader (Fabric/Forge/NeoForge).
2. Put it in the mods/ folder of your server.
3. Start the server once. AuthCore creates its files automatically:

   config/authcore/
   ├── settings.conf      ← the main configuration (explained in section 4)
   ├── messages.conf      ← every message players see (translations included)
   ├── ip-rules.conf      ← per-IP allow/deny rules
   ├── security.log       ← all security events
   ├── backups/           ← automatic database backups
   └── database/          ← the SQLite database (or your chosen DB)
   

What you should see in the console (the startup banner):

  AuthCore - The Fortress Framework for Minecraft Servers
  Version          : 1.0.0
  Minecraft        : 1.21.11
  ...
  Security Summary:
    - Password Hashing        : argon2
    - 2FA (TOTP)              : disabled
    - Sessions                : enabled

If the banner shows a warning about an untested version, the mod still works, it just means the version wasn't in the officially tested set yet. If the server crashes or won't start, jump to section 7 (Troubleshooting).

3. The first player experience (how it works)

This is the flow your players will see, understanding it makes every setting below obvious:

1. A player joins → they land in the lobby (spawn): no chat, no commands, no movement (all configurable), blindness/invisibility if configured.
2. Premium (paid) accounts are detected automatically - on online-mode servers the server itself verifies every session; on offline-mode servers AuthCore re-runs the vanilla encryption handshake and verifies with the server's own Mojang session service (never blocking the server thread). Verified players are auto-logged-in with a null password (no generated password is stored), including auto-retrying while the session API is temporarily unreachable. A player who chose password login (/account set-mode offline) is never auto-logged-in.
3. Offline-mode players run /register <password> <confirm>.
4. They run /login <password>.
5. If 2FA is enabled, they are asked for their TOTP code (from their authenticator app) or an email code.
6. They are released into the world. On their next join, their session resumes automatically (same IP), no password needed until the session expires.

🧠 Newbie question: "do my players need to install anything?", No. Plain vanilla players just type /register and /login in chat.

4. settings.conf, the important parts

All settings live in config/authcore/settings.conf (HOCON format). Reload changes with /authcore reload, no restart needed.

⚠️ Recommended values, not defaults. The snippets below show what to set for a secure setup. Defaults differ (e.g. 2FA is off by default). The full reference with every default is docs/CONFIG.md, bookmark it.

4.1 Server mode & authentication

The server's online/offline mode is always taken automatically from server.properties (the online-mode line) - there is no server-mode setting anymore. Premium auto-login is on by default and works the same on online and offline-mode servers:

session {
  authentication {
    allow-totp-support = true        # 2FA with an authenticator app (default: false)
    email-otp-support = false        # 2FA via email code (requires SMTP, see 4.5)
    require-mfa-for-sensitive = true # players with 2FA must verify it before /account set-password
    max-login-attempts = 8           # wrong-password attempts before kick (default: 8)
    block-duplicate-session = true   # the same account cannot be online twice
    premium-auto-login = true        # verified Mojang accounts log in automatically (default: true)
    allow-offline-players = true     # offline (cracked) players may join and register/login
    allow-proxy-users = false        # block players coming through proxies/VPNs
  }

  account-lock {
    enabled = true                   # lock the account after repeated failures
    max-failed-logins = 8            # failures before locking (default: 8)
    lock-duration-ms = 600000        # lock length (10 minutes)
  }

  enable-sessions = true             # remember logins (auto resume on rejoin)
  session-from-same-ip-only = true   # sessions only resume from the same IP
  timeout-ms = 3600000               # session lifetime (1 hour)
  cooldown-after-kick-ms = 120000    # wait time after being kicked
}

What to expect: with 2FA on, every login needs password + authenticator code. The recovery codes (shown at /account codes) can be used once each when the phone is lost.

Hybrid servers - offline players can join BOTH server modes: with allow-offline-players = true (the default), offline (cracked) players can join and register/login on online-mode servers too - AuthCore intercepts the login of offline-UUID clients on online-mode servers and runs them through vanilla's offline accept flow (online-mode players still use their real UUID and the normal Mojang session check). Set allow-offline-players = false to make the server online-mode-only everywhere: offline-mode players are kicked on arrival (and on online-mode servers vanilla rejects them at login). On online-mode servers keep enable-secure-profile=false in server.properties so clients without a secure chat profile (cracked/modded players) can still join and chat.

How it decides who is online-mode: only the server's own session verification counts (on online servers vanilla checks every real-UUID profile; on offline servers AuthCore re-runs the vanilla encryption handshake and verifies with the server's Mojang session service - no external API calls). The premium-auto-login config is always respected regardless of the server mode (on by default): verified players are signed in automatically and are never given a generated password (their stored password stays null). If auto-login is turned off, those players are treated like any standard account - since their password is null they are asked to /register on their next re-auth (their online-mode status is preserved, so auto-login resumes when the config is re-enabled). Everyone else is asked to /register or /login.

Players can switch their own login style with /account set-mode online (automatic login) or /account set-mode offline (password login - players who already have a password simply log in with it; auto-login accounts with no password are asked to register with /register on their next join). Admins can force either mode with /authcore set-mode online|offline <player>.

4.2 Lobby (the waiting area)

lobby {
  allow-chat = false                  # can players chat before logging in?
  allow-commands = false              # can they use commands? (whitelist below)
  whitelisted-commands = ["login", "account", "register"]
  use-whitelist-as-blacklist = false  # true = block only the listed commands
  allow-movement = false              # lock players in place
  allow-item-drop = false             # no dropping items in the lobby
  allow-item-pickup = false
  allow-item-use = false
  allow-block-interaction = false
  max-lobby-users = 50                # lobby size limit (kicks extra joiners)
  captcha { enabled = true }          # human verification: physical task for bot-like players
  announcements = ["Welcome! Register with /register <password> <confirm>"]
}

4.3 ClientGuard (anti-bot / anti-bypass)

AuthCore profiles every player's behavior and raises a risk score when something looks automated. Signals: missing client settings, ghost clients (no chat/auth), movement/click/ chat/payload floods, tab-completion probing, fake companion clients, confusable names.

session {
  client-guard {
    enabled = true
    ghost-kick-after-sec = 45          # kick silent bots after 45s idle in the lobby
    settings-timeout-sec = 20          # flag clients that never send their settings
    move-packet-rate-per-sec = 120
    lobby-click-rate-per-sec = 12
    payload-rate-per-sec = 15
    lobby-chat-rate-per-sec = 3
    risk-alert-threshold = 40          # log + webhook alert
    risk-kick-threshold = 70           # kick from the lobby
    risk-2fa-threshold = 50            # high-risk players must complete 2FA
    re-challenge-interval-sec = 30     # periodic companion attestation
    challenge-timeout-sec = 10
    companion-spoof-risk = 40
    concurrent-login-policy = "kick-new"   # "allow" | "kick-new" | "kick-old"
    allowed-name-regex = "^[A-Za-z0-9_]{3,16}$"
    detect-confusable-names = true     # flag Stеvе (lookalike) names
    require-token-for-resume = true
    vanilla-resume-risk = 10
    max-payload-bytes = 8192
  }
}

Vanilla players are never locked out. Every check is risk-based; the normal chat login always works.

4.4 Network-wide single sign-on (SSO)

With Redis enabled, a player who logs in on one server of your network is trusted on all of them:

session {
  sso {
    enabled = true        # requires database.redis.enabled = true
    session-ttl-min = 30  # how long a login is honoured network-wide
    trust-vanilla = false # also trust vanilla clients when a remote session exists
  }
}

4.5 Email (for email 2FA + recovery)

email {
  enabled = true
  host = "smtp.gmail.com"
  port = 587
  username = "you@gmail.com"
  password = "your-app-password"
  from = "you@gmail.com"
}

4.6 Web admin panel

session {
  web-panel {
    enabled = true
    host = "127.0.0.1"          # keep local, tunnel it (or bind 0.0.0.0 with a token)
    port = 25570
    token = "change-me-long-random-token"
    # https-enabled = true      # optional HTTPS (self-signed keystore)
  }
  honeypot { enabled = true; port = 25571 }   # traps and logs port scanners
}

The panel rejects requests without a token (401), with a wrong token (401) and locks out brute force after repeated failures (429). A readonly-token exists for status-only access. How to use the panel: docs/WEBPANEL.md.

4.7 Databases (all optional)

database {
  sqlite { file = "authCore-db.sqlite" }        # default: zero-config
  # mysql { enabled = true; host = "..."; ... }
  # postgres { enabled = true; ... }
  redis { enabled = false; host = "localhost"; port = 6379 }  # sessions sync, SSO, bans, event bus
}

🧠 Newbie question: "which database should I use?", Start with SQLite (zero setup). Move to MySQL/PostgreSQL only when you run several servers on one account database, and add Redis when you want network-wide sessions/SSO.

4.8 Feature-by-feature setup (every feature, with scenarios)

This section explains every feature AuthCore ships: what it protects, the exact config to enable it, and a real-world scenario showing when you want it. All settings live in config/authcore/*.conf and hot-reload with /authcore reload.

4.8.1 Human verification (action captcha)

What it does. AuthCore's single human-verification method. After every login or register it observes the player for a short window and scores the session across many independent signals: ghost pattern (no look/move/click/chat/settings), ClientGuard risk, instant login (password typed within seconds of joining - bots use stored credentials), failed attempts before success, missing 2FA on a TOTP account, fresh account age, and fast reconnect loops. Trust signals (premium, valid session token, previously trusted account, already passed the challenge) subtract from the score. Only when the total reaches bot-score-threshold is the player challenged with a physical task: sneak for N seconds, jump N times, or look up at the sky - things only a real client can do.

lobby {
  captcha {
    enabled = true                  # the whole verification system (default: true)
    observation-window-sec = 45     # how long we watch before deciding (default: 45)
    auto-challenge-ghosts = true    # zero-behavior players are always challenged
    trigger-risk-threshold = 60     # ClientGuard risk that alone justifies a challenge
    bot-score-threshold = 60        # total score needed to challenge (default: 60)

    # signal weights (bot signals ADD, trust signals SUBTRACT)
    instant-login-sec = 5           # login within 5s of joining = +25 score
    failed-attempt-score = 10       # 2+ wrong passwords this session
    missing-mfa-score = 20          # TOTP account logged in without the code
    fresh-account-hours = 24        # account younger than a day = +15
    fast-rejoin-sec = 20            # reconnect within 20s = +20
    trusted-score = 20              # previously trusted account = -20
    premium-score = 20              # Mojang-verified = -20
    session-token-score = 20        # valid companion token resume = -20
    already-verified-score = 50     # passed earlier this session = -50

    action-ttl-ms = 60000           # time to finish the task (default: 60s)
    action-sneak-seconds = 3        # sneak challenge length
    action-jump-count = 5           # jump challenge count
    action-look-up-seconds = 3      # look-up challenge length
    disable-when-tps-below = 0      # skip during lag spikes (0 = never)
  }
}

Scenario - public survival server. Every login is scored. A returning player types their password slowly, moves, looks around and chats - they score 0 and never see the captcha. A bot that joins with a stolen password, logs in in 2 seconds and then stands still scores: instantLogin +25, ghost +40, freshAccount +15 = 80 > 60 and is challenged (and kicked if it cannot sneak/jump/look up). To make verification stricter, raise bot-score-threshold to 80; to catch more bots, lower it to 40.

4.8.2 MFA / 2FA (TOTP, email OTP, recovery codes)

What it does. Adds a second factor after the password. TOTP uses an authenticator app (Google Authenticator, Aegis, Authy); email OTP sends a one-time code via SMTP; recovery codes are single-use backups shown at /account codes. Sensitive actions (password change, unregister) can require MFA again (step-up).

session {
  authentication {
    allow-totp-support = true       # authenticator-app 2FA (default: false)
    email-otp-support = false       # email-code 2FA (needs SMTP, see 4.5)
    require-mfa-for-sensitive = true # step-up before /account set-password
  }
}
email { enabled = true; host = "smtp.gmail.com"; port = 587; username = "you@gmail.com"; password = "app-password"; from = "you@gmail.com" }

Scenario - staff accounts. Turn TOTP on and tell staff to scan the QR code shown at first join. Even if a staff password leaks in a credential dump, the attacker cannot answer the TOTP code. missing-mfa-score in the human verification then also flags password-only logins on these accounts as suspicious.

4.8.3 Brute force & account lock

What it does. Caps wrong-password attempts per session, applies an exponential kick cooldown for repeat offenders and can lock the account entirely after N failures (the lock is persisted and survives restarts).

session {
  authentication { max-login-attempts = 8 }
  cooldown-after-kick-ms = 120000
  progressive-punishment { enabled = true; base-cooldown-ms = 5000; multiplier = 3.0; max-cooldown-ms = 300000 }
  account-lock { enabled = true; max-failed-logins = 8; lock-duration-ms = 600000 }
}

Scenario - credential-stuffing wave. An attacker tries leaked passwords against many accounts from one IP. Each failure counts; after 8 failures the account locks for 10 minutes and the IP gets blocked by AuthIntelligence (see 4.8.6), so the wave burns itself out without ever succeeding.

4.8.4 Sessions & trusted players

What it does. Successful logins create a server-side session (token rotated every login, IP-bound by default) so players do not re-type their password every rejoin. The account is also marked "trusted" for bypass-captcha-hours - which now only reduces the verification score (it never bypasses it entirely).

session {
  enable-sessions = true
  session-from-same-ip-only = true
  timeout-ms = 3600000
  trusted {
    enabled = true
    bypass-captcha-hours = 24
  }
}

Scenario - minigame network with hub transfers. A player logs in once, then hops between hub and minigame servers. Sessions make every hop instant; on a Redis-backed network, SSO (4.8.8) extends the same trust across the whole network.

4.8.5 ClientGuard (anti-bot / anti-bypass)

What it does. Builds a per-player behavioral profile from packet-level signals (brand anomaly, missing settings, ghost behavior, move/click/chat/payload floods, tab probing, fake companion attestation, confusable names) and converts them into a 0-100 risk score with a decision matrix: alert → require 2FA → kick.

session {
  client-guard {
    enabled = true
    ghost-kick-after-sec = 45
    settings-timeout-sec = 20
    risk-alert-threshold = 40
    risk-2fa-threshold = 50
    risk-kick-threshold = 70
    concurrent-login-policy = "kick-new"
    detect-confusable-names = true
    require-token-for-resume = true
  }
}

Scenario - lobby flooders. A client joins, never sends its settings packet, spams movement packets and probes commands. Each signal adds weight; at risk 70 the lobby kicks it - before it can even attempt a login. The same risk score feeds the human-verification scoring from 4.8.1.

4.8.6 AuthIntelligence (login intelligence)

What it does. Detects attacks on the login process itself: password spraying (one password against many accounts), per-IP login floods, 2FA brute force (right password + wrong code = compromised password), guess-then-success, mass registration (bot farms), session-token replay and post-login account takeover (new network + fast password change). Each detection writes a security log + webhook alert and can block the IP.

session {
  auth-intelligence {
    password-spray { enabled = true; window-min = 10; max-accounts = 8 }
    login-flood { enabled = true; window-min = 10; max-failures-per-ip = 10; block-minutes = 30 }
    totp-bruteforce { enabled = true; window-min = 10; max-failures = 5 }
    success-after-failures { enabled = true; min-failures = 3 }
    registration-farm { enabled = true; window-min = 10; max-accounts-per-ip = 3; block-minutes = 30 }
    session-replay { enabled = true }
    ato-pattern { enabled = true; window-min = 30 }
  }
}

Scenario - bought-account reseller. A script tries one freshly bought password against hundreds of accounts: password-spray fires the webhook after 8 accounts. Later, one succeeds and the script immediately changes the password from a new IP: ato-pattern alerts that the account was taken over.

4.8.7 Rate limits & IP rules

What it does. Per-IP join/login rate limits stop bot floods before they reach the auth logic; ip-rules.conf allows or denies specific IPs/networks outright.

session {
  rate-limit {
    enabled = true
    max-joins-per-window = 5
    window-ms = 60000
    command-cooldown-ms = 1000
    alert-on-fast-rejoin = true
    fast-rejoin-window-ms = 500
  }
}
# config/authcore/ip-rules.conf
# allow = ["127.0.0.1", "192.168.0.0/16"]
# deny  = ["45.155.0.0/16"]

Scenario - DDoS-grade join flood. Attackers cycle thousands of fake connections per minute. max-joins-per-window caps each IP; alert-on-fast-rejoin flags the disconnect-rejoin loop; a known abusive range goes straight to deny in ip-rules.conf.

4.8.8 SSO & Redis network features

What it does. With Redis enabled: network-wide single sign-on (login on one server = trusted on all), duplicate-session blocking across servers, remote bans and a cross-server security event bus.

database { redis { enabled = true; host = "localhost"; port = 6379 } }
session {
  sso { enabled = true; session-ttl-min = 30; trust-vanilla = false }
}

Scenario - 3-server network. A player logs in on the lobby server. Without SSO they re-type the password on each game server; with SSO the lobby broadcasts the login via Redis and the game servers trust it instantly. A ban on one server propagates to all.

4.8.9 Web panel & honeypot

What it does. The web panel is a token-protected admin dashboard (player lists, lookups, actions, metrics) with brute-force lockout (429 after 5 wrong tokens). The honeypot opens a decoy port that logs any connection as HONEYPOT_HIT - perfect for spotting port scanners before they find the real game port.

session {
  web-panel {
    enabled = true
    host = "127.0.0.1"
    port = 25570
    token = "change-me-long-random-token"
    # readonly-token = "..."
    # https-enabled = true
  }
  honeypot { enabled = true; port = 25571 }
}

Scenario - hosting a server for strangers. Bind the panel to 127.0.0.1 and tunnel it over SSH; enable HTTPS with the self-signed keystore for remote admin. The honeypot on a random port logs every probe, so you see attackers 'knocking' before they ever reach 25565.

4.8.10 Online-mode accounts & proxy support

What it does. Premium (paid) accounts are auto-verified through the server's own Mojang session service (outage-proof, no API calls) and auto-login - on online and offline-mode servers, with no server-mode setting needed (it's always read from server.properties). Auto-login players keep a null password; they can switch to password login with /account set-mode offline (admins: /authcore set-mode offline <player>). Proxy support parses BungeeCord-style or Velocity-modern forwarding (HMAC-verified) so the real client IP is used for every check; the proxy plugin can even block unauthenticated players before they reach the backend.

session {
  authentication {
    premium-auto-login = true
  }
  proxy-support { enabled = true; protocol = "auto" }  # auto | bungeecord | velocity-modern
}

Scenario - network behind Velocity. Enable proxy-support with the Velocity shared secret; every GeoIP, rate limit, session and intelligence check then uses the real player IP, and proxy-side auth (velocity-plugin) rejects unauthenticated joins at the proxy itself - the backend never even sees them.

4.8.11 Maintenance, shadow-ban, auto-whitelist & announcements

What it does. /authcore maintenance on blocks all joins with a custom message. Shadow-ban hides security blocks behind a generic "connection lost" so attackers cannot tell they were detected. Auto-whitelist adds every registered account to the vanilla whitelist. Rotating announcements greet authenticated players.

session {
  maintenance { enabled = false; kick-message = "Server under maintenance." }
  shadow-ban { enabled = false }
  auto-whitelist { enabled = true }
}
lobby {
  announcements = ["Welcome, %player%!"]
  announcement-interval-sec = 300
}

Scenario - launching a new map. Flip maintenance on while uploading the world, then off. Shadow-ban keeps bot operators blind to your detection while you gather intel. Auto-whitelist keeps the server invite-only after a closed beta.

4.8.12 Backups, Discord linking & locales

What it does. Automatic database backups (SQLite file copy, rotating) run on an interval; Discord account linking connects in-game accounts to Discord via a code flow; 7 built-in locales plus custom messages-<lang>.conf files localize every message.

session {
  backup { interval-hours = 24; keep = 10 }
  discord-link { enabled = true }
}
language = "de"   # or en, es, fr, pt, ru, zh, or a custom messages-<lang>.conf

Scenario - community server ops. Backups run nightly and keep 10 copies, so a bad config or a deleted account is recoverable. Discord linking gives staff a way to recover accounts through the linked Discord ID. German players get language = "de" with the bundled translation.

5. Admin commands

All admin commands need OP 3+, a LuckPerms node, or console access:

Player commands: /register, /login, /account set-password, /account codes (recovery codes), /account email, /account nickname, /account logout, /account set-mode online|offline, /account unregister, /account recover, /discord link, /discord unlink.

6. Security recommendations (checklist)

1. The server's mode is always read from server.properties (there is no server-mode setting anymore) - it needs no configuration; on online-mode servers keep enable-secure-profile=false in server.properties so clients without a secure chat profile can still join and chat.
2. Enable 2FA (allow-totp-support = true), recovery codes are single-use.
3. Keep password-hash-algorithm = "argon2" (never md5).
4. Put a long random token on the web panel and keep it on 127.0.0.1 (tunnel it).
5. Keep ClientGuard defaults on; check /authcore whois + security.log for signals.
6. Use a proxy (Velocity/BungeeCord) with modern forwarding for networks; enable SSO with Redis when you run multiple servers.
7. Backups are automatic (session.backup.interval-hours), store them off-server.
8. When something looks wrong, share the error code from the console (format AC-<hex>-<hex>-<hex>-<hex>) with the mod author, it pinpoints the exact failure without exposing internals.

🧠 Want the why behind each item? The full threat model lives in docs/SECURITY.md.

7. Troubleshooting

8. Learning path, go deeper

This guide intentionally keeps things simple. When you're ready, each topic links to its full documentation:

🧭 Suggested order for a newbie: read this guide → read FLOWS.md to see exactly what happens on join, register, login and premium verification → skim CONFIG.md once → then read PROXY.md and WEBPANEL.md only when you set those up.

9. Getting help

• Bugs & ideas: open an issue on GitHub
• Questions: Discussions
• Discord / webhook alerts: see section 4.6 and WEBPANEL.md
• When reporting a bug: include the console error code (AC-...) and the version from the startup banner, it pinpoints the failure without exposing internals.