🧭 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, your client companion 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. They run /register <password> <confirm>.
3. They run /login <password>.
4. If 2FA is enabled, they are asked for their TOTP code (from their authenticator app) or an email code.
5. They are released into the world. On their next join, their session resumes automatically (same IP), no password needed until the session expires.
6. If they have the client companion (the same jar installed on their client), the login screen appears automatically, sessions resume with a secure session token, and the server can attest the client (anti-bot).

🧠 Newbie question: "do my players need to install anything?", No. The companion is optional convenience. 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

session {
  server-mode = "offline"            # "online" = premium auto-auth, "offline" = passwords
                                     # ← set to "offline" on cracked servers!

  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        # premium (paid) players log in automatically
    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.

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 }          # text captcha on register/login
  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. The companion (same jar on the client) is optional, it just earns more trust and convenience.

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.

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 unregister, /account recover, /discord link, /discord unlink.

6. Security recommendations (checklist)

1. Set session.server-mode = "offline" on cracked servers.
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 → 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.