Skip to content

MaxAuth Wiki (CZ)

Jump to bottom
Dj Nejk edited this page Jun 9, 2026 · 4 revisions

MaxAuth Wiki

MaxAuth je autentizační plugin pro Minecraft networky běžící na proxy. Chrání cracked účty heslem, podporuje premium hráče, řeší UUID, sessions, dvoufázové ověření, captcha mapu a ochranu backend serverů.

Plugin se skládá ze dvou částí:

  • Proxy plugin pro Velocity nebo BungeeCord.
  • Backend plugin pro Paper/Spigot servery za proxy.

Proxy část je hlavní. Rozhoduje, jestli je hráč premium, cracked nebo Bedrock, jaké má UUID, jestli je přihlášený, kam se má přesměrovat a jaký profil se uloží do databáze.

Backend část chrání hráče během autorizace. Umí blokovat pohyb, interakce, chat, příkazy, inventory, zobrazovat captcha mapu, držet hráči čas/počasí a ověřovat, že hráč přišel přes správnou proxy.

Obsah

Podporované platformy

Proxy:

  • Velocity
  • BungeeCord

Backend:

  • Paper
  • Spigot

Databáze:

  • SQLite
  • MySQL
  • MariaDB
  • PostgreSQL

Java:

  • Java 17+

Volitelné backend pluginy:

  • ProtocolLib
  • BungeeGuard
  • PlaceholderAPI

Základní princip

MaxAuth funguje jako proxy-first autentizační systém.

Hráč se připojí na proxy. Proxy zjistí typ účtu, načte nebo vytvoří profil a rozhodne, jestli má hráč jít rovnou na main server, nebo nejdřív do limbo serveru na registraci/přihlášení.

Nepřihlášený cracked hráč je poslaný na limbo server. Tam backend plugin drží hráče pod kontrolou, dokud se nepřihlásí nebo nezaregistruje. Po úspěšné autorizaci proxy pošle backendu nový stav hráče a podle konfigurace ho přesměruje na main server.

Premium hráči se ověřují přes Mojang resolver a můžou být přihlášeni automaticky. Bedrock hráči jsou řešeni přes Floodgate/Geyser podporu, pokud je zapnutá.

Instalace

Proxy

Vlož MaxAuth jar do složky pluginů proxy:

velocity/plugins/

nebo:

bungee/plugins/

Po prvním spuštění se vygeneruje proxy konfigurace. Pokud plugin zjistí, že je potřeba konfiguraci nastavit, vypíše výraznou zprávu do konzole a proxy vypne, aby se hráči nedostali na server bez ochrany.

Backend

Stejný jar vlož do každého backend serveru:

plugins/

Backend část při první instalaci vypíše varování, že config by měl být nakonfigurovaný.

Access token

Proxy i backend musí mít stejný token:

accessToken: 'dlouhy-nahodny-token'

Token slouží k ověření komunikace mezi proxy a backendem. Měl by být dlouhý, náhodný a soukromý.

Proxy konfigurace

Proxy config obsahuje hlavní nastavení pluginu.

Typ storage:

storageType: SQLITE

Podporované hodnoty:

  • SQLITE
  • MYSQL
  • MARIADB
  • POSTGRESQL

MySQL/MariaDB/PostgreSQL nastavení:

storageHost: ''
storagePort: 3306
storageDatabase: ''
storageUser: ''
storagePassword: ''

Connection pool:

connectionPoolSize: 10
connectionPoolIdle: 10
connectionPoolTimeout: 5000
connectionPoolLifetime: 1800000
connectionKeepAliveTime: 0

Pokud databáze hlásí Too many connections, sniž hlavně:

connectionPoolSize: 3
connectionPoolIdle: 1

Limbo a main servery:

limboServerNames: [limbo]
mainServerNames: [main]

Redirecty po autorizaci:

afterRegisterRedirect: true
afterLoginRedirect: true

Když je redirect zapnutý, success title/chat po loginu nebo registraci se zobrazí až po připojení hráče na main server. Když je vypnutý, zpráva se zobrazí hned na aktuálním serveru.

Registrace premium hráčů:

registerPremiumUsers: true

Captcha:

verifyCaptchaCode: false

Zapnutí/vypnutí captchy se řeší pouze na proxy. Backend config řeší jen slot mapy.

Hesla:

confirmPassword: true
passwordHashingAlgorithm: ARGON2ID
safePasswordPattern: '[\S]{6,25}'

Algoritmy nastavitelné pro nová hesla:

  • ARGON2ID - doporučeno pro nové instalace.
  • BCRYPT - doporučeno, pokud chceš široce kompatibilní moderní hash.
  • PBKDF2_SHA256
  • PBKDF2_SHA512
  • SALTEDSHA512
  • SHA256 - MaxAuth salted SHA-256, ponecháno kvůli kompatibilitě existujících configů.
  • SHA512 - MaxAuth salted SHA-512, ponecháno kvůli kompatibilitě existujících configů.

SHA256 a SHA512 jsou salted MaxAuth hashe. Klasické nesolené SHA hashe se akceptují jen pro migraci jako CSHA256 a CSHA512.

Uložené hashe hesel obsahují prefix algoritmu, takže MaxAuth umí ověřit i starší hashe po změně passwordHashingAlgorithm.

rehashPasswordWhenUsingDifferentAlgorithm: true

Při zapnutí MaxAuth po úspěšném loginu znovu zahashuje heslo hráče, pokud uložený hash používá jiný algoritmus než aktuální konfigurace. Hodí se to při migraci existujících účtů na ARGON2ID nebo BCRYPT.

Migrační algoritmy akceptované z databáze:

  • SALTEDSHA256
  • DOUBLE_SHA512
  • AUTHME_SHA256
  • AUTHME_SHA
  • PBKDF2
  • CSHA256
  • CSHA512
  • MD5VB
  • IPB3
  • IPB4
  • JOOMLA
  • MYBB
  • PHPBB
  • PHPFUSION
  • SMF
  • WBB3
  • WBB4
  • XFBCRYPT
  • ROYALAUTH
  • MD5
  • SHA1
  • DOUBLE_MD5
  • DOUBLE_SHA1
  • BCRYPT2Y

Tyto migrační algoritmy se akceptují pouze pro ověření starých hesel. Pro nové registrace by se používat neměly.

Sessions:

manuallySessionTime: 720
automaticSessionTime: 10

Bezpečnost loginu:

maximumLoginTriesBeforeDisconnection: 5
addressBanDuration: 10
maximumAuthorisationTime: 90

E-mail recovery:

emailEnabled: true
mailHost: ''
mailPort: 25
mailUser: ''
mailPassword: ''
mailName: Your server name
mailEncryption: STARTTLS
mailUseTLS: true
passwordRecoverySubject: The password recovery

Při emailEnabled: false se neposílají email reminder zprávy a vypnou se /changeemailaddress, /requestpasswordrecovery, /confirmpasswordrecovery i odpovídající /maxauth admin subcommandy.

mailEncryption určuje, jak se MaxAuth připojí na SMTP server:

  • NONE pro obyčejné SMTP.
  • STARTTLS pro SMTP servery, které spojení po navázání povýší na šifrované, typicky port 587.
  • SSL pro implicitní TLS SMTP servery, typicky port 465.

mailUseTLS zůstává jen jako kompatibilní fallback pro starší configy. Nové nastavení by mělo používat mailEncryption.

2FA:

secondFactorEnabled: true

Při secondFactorEnabled: false se neposílají 2FA reminder zprávy, existující 2FA tokeny se při loginu ignorují a vypnou se /requestsecondfactor, /activatesecondfactor, /deactivatesecondfactor i odpovídající /maxauth admin subcommandy.

Backend konfigurace

Backend config řeší ochranu hráče na serveru.

Access token:

accessToken: 'stejny-token-jako-na-proxy'
accessTokenDisabled: false

accessTokenDisabled zapínej jen tehdy, když je backend chráněný jinak, například firewallem, BungeeGuardem nebo Velocity modern forwardingem.

Trusted proxy IPs:

trustedProxyIps: []

Prázdný list znamená, že backend kontroluje jen MaxAuth token. Podporuje přesné IP i CIDR rozsahy, například ['127.0.0.1', '10.0.0.0/8'].

Captcha mapa:

captchaMapSlot: 1
captchaMessage: 'Your captcha is %captcha_code%'

captchaMapSlot je slot 1-9.

Ochrana nepřihlášených hráčů:

restrictedMovement: true
restrictedInteractions: true
blindnessEffect: true

Čas a počasí během autorizace:

setPlayerTime: day
setPlayerWeather: clear

Podporované příklady času:

  • day
  • noon
  • night
  • midnight
  • 18:15
  • 1000

Podporované počasí:

  • clear
  • rain
  • thunder

Prázdná hodnota funkci vypne:

setPlayerTime: ''
setPlayerWeather: ''

Spawn lokace:

spawnLocation: ''

Nastavení přes hru:

/maxauth spawnset

Příkaz se spouští na proxy, ale hráč musí být připojený na backend server s MaxAuth backend pluginem. Backend uloží aktuální lokaci hráče včetně yaw a pitch.

Příkazy pro hráče

Přihlášení a registrace

/login <password>
/login <password> <code>
/register <password>
/register <password> <password>
/register <password> <captcha>
/register <password> <password> <captcha>

/login <password> <code> se používá při zapnutém dvoufázovém ověření.

Tvar /register závisí na:

  • confirmPassword
  • verifyCaptchaCode

Sessions

/startsession
/destroysession

/startsession vytvoří manuální session. Hráč se pak při dalším připojení ze stejné adresy může přihlásit automaticky.

/destroysession session zruší.

Heslo

/changepassword <current-password> <new-password>
/changepassword <current-password> <new-password> <new-password>
/createpassword <password>
/createpassword <password> <password>

Varianta s opakováním hesla závisí na confirmPassword.

Účet

/unregister <password>
/premium <password>
/cracked <password>
/confirm

Pokud je zapnuté riskyCommandsConfirmation, rizikové akce vyžadují potvrzení přes /confirm.

E-mail recovery

/changeemailaddress <password> <email>
/requestpasswordrecovery <email>
/confirmpasswordrecovery <recovery-code> <password> [password]

Recovery funguje jen se správně nastaveným SMTP v proxy configu. Hráčské recovery příkazy fungují pouze během login fáze, tedy před tím, než se hráč přihlásí. Díky tomu nejde spouštět ani potvrzovat obnovu hesla z už přihlášené session.

Pokud je zapnuté confirmPassword, /confirmpasswordrecovery vyžaduje zopakované heslo:

/confirmpasswordrecovery <recovery-code> <password> <password>

Discord audit webhooky:

sendDiscordWebhooks:
  - name: admin-audit
    enabled: false
    url: ''
    adminDiagnostics: true
    adminProfileViews: true
    adminProfileMutations: true
    adminAuthActions: true
    adminRecoveryActions: true
    adminSecondFactorActions: true
    adminSpawnSet: true
    adminReload: true
    successfulActions: true
    failedActions: true

Můžeš mít více webhooků a každý může posílat jiné kategorie audit logů.

Dvoufázové ověření

/requestsecondfactor
/activatesecondfactor <password> <code>
/deactivatesecondfactor <password> <code>

Postup:

  1. Hráč se přihlásí.
  2. Spustí /requestsecondfactor.
  3. Dostane klikací QR odkaz.
  4. QR naskenuje v TOTP aplikaci.
  5. Aktivuje 2FA přes /activatesecondfactor <password> <code>.
  6. Další login používá /login <password> <code>.

Admin příkazy

Admin příkazy jsou dostupné pod:

/maxauth
/mauth

Základ:

/maxauth
/maxauth help
/maxauth reload
/maxauth configcheck
/maxauth checkflow
/maxauth testmail <email>
/maxauth spawnset

/maxauth testmail <email> pošle diagnostický recovery e-mail s nickem vykonavatele příkazu a recovery kódem 123456. Do chatu vypíše SMTP host, port, režim šifrování, dobu odeslání a stav úspěchu nebo chyby.

Správa profilů:

/maxauth viewuserprofile <nickname|uuid>
/maxauth viewuserprofiles <address>
/maxauth purgeuserprofile <nickname|uuid>
/maxauth mergepremiumuserprofile <premium-nickname|premium-uuid> <target-nickname|target-uuid>

Zásahy do účtu:

/maxauth login <nickname|uuid>
/maxauth register <nickname|uuid> <password>
/maxauth createpassword <nickname|uuid> <password>
/maxauth changepassword <nickname|uuid> <password>
/maxauth startsession <nickname|uuid>
/maxauth destroysession <nickname|uuid>
/maxauth unregister <nickname|uuid>
/maxauth premium <nickname|uuid>
/maxauth cracked <nickname|uuid>
/maxauth changeemailaddress <nickname|uuid> <email>

Recovery a 2FA:

/maxauth requestpasswordrecovery <nickname|uuid>
/maxauth confirmpasswordrecovery <nickname|uuid> <recovery-code>
/maxauth requestsecondfactor <nickname|uuid>
/maxauth activatesecondfactor <nickname|uuid>
/maxauth deactivatesecondfactor <nickname|uuid>

Admin příkazy používají profily podle nickname nebo UUID. U vybraných příkazů plugin doplňuje online hráče v tab-complete.

Permise

maxauth.admin

Umožňuje používat admin příkazy pod /maxauth a /mauth.

maxauth.command.reload

Umožňuje reload přes /maxauth reload nebo reload command.

Backend plugin používá také:

maxauth.admin

Permission je defaultně pro OP.

Autentizační flow

Nový cracked hráč

  1. Hráč se připojí na proxy.
  2. Proxy vytvoří cracked profil.
  3. Hráč je poslán na limbo server.
  4. Backend ho omezí podle configu.
  5. Hráč použije /register.
  6. Proxy uloží heslo a nastaví hráče jako přihlášeného.
  7. Backend dostane nový stav hráče.
  8. Hráč je podle configu přesměrován na main server.

Registrovaný cracked hráč

  1. Hráč se připojí.
  2. Proxy načte profil z databáze.
  3. Pokud má platnou session, přihlásí ho automaticky.
  4. Pokud session nemá, pošle ho na limbo server.
  5. Hráč použije /login.
  6. Po úspěchu je přesměrován na main server.

Premium hráč

  1. Proxy ověří nickname přes Mojang.
  2. Hráč dostane online UUID.
  3. Podle konfigurace se profil automaticky vytvoří.
  4. Hráč je přihlášen bez hesla.

Bedrock hráč

Bedrock chování závisí na:

floodgateSupport:
  enabled: true
  useApiVerification: true

Při zapnuté podpoře plugin upravuje UUID a chování pro Floodgate/Geyser hráče.

Dvoufázové ověření

2FA používá TOTP kódy z aplikací jako Google Authenticator, Authy nebo Aegis.

Zapnutí:

/requestsecondfactor
/activatesecondfactor <password> <code>

Vypnutí:

/deactivatesecondfactor <password> <code>

Login se zapnutým 2FA:

/login <password> <code>

Špatný 2FA kód se chová podobně jako špatné heslo a počítá se do login failů.

2FA je určené pro cracked/password účty. Premium a Bedrock účty ho aktuálně nepoužívají. Celou 2FA část lze vypnout přes secondFactorEnabled: false.

Captcha

Captcha se zapíná na proxy:

verifyCaptchaCode: true

Backend nastavuje slot mapy:

captchaMapSlot: 1

Pokud je captcha zapnutá, nový neregistrovaný hráč dostane captcha mapu a musí použít správný register příkaz podle configu, například:

/register <password> <captcha>

nebo:

/register <password> <password> <captcha>

Limbo a main servery

limboServerNames jsou servery pro nepřihlášené hráče:

limboServerNames: [limbo]

mainServerNames jsou servery pro přihlášené hráče:

mainServerNames: [main]

Lze nastavit více serverů:

mainServerNames: [lobby, survival, skyblock]

Více serverů slouží jako fallback. Pokud první server není dostupný, plugin může použít další dostupný server z listu.

Messages

Messages jsou na proxy:

plugins/maxauth/messages.yml

Podporované typy zpráv:

  • chat
  • title
  • subtitle
  • actionbar
  • bossbar
  • kickscreen

Každý message key má komentář s typem:

loginSuccessLoggedChat: '{prefix}&8» &aYou have successfully logged in.' #type: chat

Prefix:

prefix: '{#55ff55}M{#55ff8e}a{#55ffc6}x{#55ffff}A{#71e3e3}u{#8ec6c6}t{#aaaaaa}h '

Barvy:

&aGreen text
{#55ff55}Hex text

Gradient:

{#55ff55>}Text{<#55ffff}
{#55ff55>}%nickname%{<#55ffff}

Víceřádkové zprávy:

loginErrorTimeElapsed: #type: kickscreen
  - '{prefix}'
  - ' '
  - '&cAn authorisation time elapsed!'

Register varianty:

joinRequireRegisterTitle_1
joinRequireRegisterTitle_2
joinRequireRegisterTitle_3
joinRequireRegisterTitle_4
joinRequireRegisterSubTitle_1
joinRequireRegisterSubTitle_2
joinRequireRegisterSubTitle_3
joinRequireRegisterSubTitle_4
joinRequireRegisterChat_1
joinRequireRegisterChat_2
joinRequireRegisterChat_3
joinRequireRegisterChat_4
registerErrorUsage_1
registerErrorUsage_2
registerErrorUsage_3
registerErrorUsage_4

Pořadí variant:

  1. confirmPassword=false, verifyCaptchaCode=false
  2. confirmPassword=true, verifyCaptchaCode=false
  3. confirmPassword=false, verifyCaptchaCode=true
  4. confirmPassword=true, verifyCaptchaCode=true

Automatické doplňování souborů

MaxAuth umí automaticky doplnit nové položky do existujících souborů.

Platí pro:

  • proxy configuration.yml
  • backend configuration.yml
  • proxy messages.yml

Když v nové verzi přibude nová položka, plugin ji přidá nahoru do souboru i s komentářem z defaultní konfigurace.

Databáze

SQLite je nejjednodušší varianta pro test nebo malý server.

Pro větší network je lepší:

  • MySQL
  • MariaDB
  • PostgreSQL

Příklad MySQL:

storageType: MYSQL
storageHost: '127.0.0.1'
storagePort: 3306
storageDatabase: 'maxauth'
storageUser: 'maxauth'
storagePassword: 'password'

U hostingů s nízkým limitem connectionů nastav menší pool:

connectionPoolSize: 3
connectionPoolIdle: 1

Migrace z JPremium

MaxAuth umí migrovat data z původní JPremium SQL tabulky user_profiles.

Při startu proxy se provede kontrola aktuální databáze. Pokud existuje tabulka user_profiles a cílová MaxAuth tabulka je jiná, například maxauth_users, plugin vytvoří nebo aktualizuje:

plugins/maxauth/migrate_DB.yml

V souboru je pre-report s počty:

  • legacyAccounts - počet řádků ve staré JPremium tabulce.
  • existingMaxAuthAccounts - počet účtů v cílové MaxAuth tabulce.
  • accountsToMigrate - počet řádků, které půjde převést.
  • collisionRowsToSkip - počet řádků, které budou přeskočené kvůli kolizi.
  • collisionsByUniqueId - kolize podle UUID.
  • collisionsByPremiumId - kolize podle premium UUID.
  • collisionsByNickname - kolize podle posledního nickname.
  • missingRequiredColumns - chybějící sloupce, pokud stará tabulka není kompatibilní.

Migrace je ručně potvrzovaná. Vygenerovaný soubor nejdřív obsahuje:

migrateAfterRestart: false

Po kontrole reportu nastav:

migrateAfterRestart: true

Potom restartuj proxy. MaxAuth převede data do aktuální tabulky. Pokud už účet existuje v MaxAuth podle uniqueId, premiumId nebo lastNickname, vyhraje existující MaxAuth profil a JPremium řádek se přeskočí.

Po úspěchu MaxAuth:

  • odstraní migrateAfterRestart,
  • zapíše finalReport,
  • přejmenuje starou tabulku user_profiles na user_profiles_old.

Pokud user_profiles_old už existuje, použije se název s časovou značkou, aby se nepřepsala starší záloha.

Migrace používá stejnou databázovou konfiguraci jako MaxAuth. JPremium tabulka tedy musí být ve stejné databázi, ve které je cílová MaxAuth tabulka.

Bezpečnost backendu

Backend servery by neměly být přístupné přímo z internetu.

Doporučené nastavení:

  • Povolit přístup na backend jen z proxy IP.
  • Použít firewall.
  • Použít Velocity modern forwarding nebo BungeeGuard.
  • Použít dlouhý náhodný accessToken.
  • Nechat accessTokenDisabled: false, pokud si nejsi jistý.

Když proxy část MaxAuth nenaběhne správně, plugin má proxy vypnout. To chrání network před tím, aby hráči vešli na server bez správného UUID a auth stavu.

Časté problémy

Hráč nevidí success zprávu po loginu/registeru

Zkontroluj:

afterLoginRedirect: true
afterRegisterRedirect: true

Pokud je redirect zapnutý, success zpráva se zobrazí až po připojení na main server. Pokud je redirect vypnutý, zobrazí se hned na limbo serveru.

Captcha se zobrazuje, i když ji nechci

Captcha se vypíná na proxy:

verifyCaptchaCode: false

Backend captchaMapSlot řeší jen slot.

Databáze hlásí Too many connections

Sniž connection pool:

connectionPoolSize: 3
connectionPoolIdle: 1

Pokud nejde ani phpMyAdmin, problém je přímo v databázi nebo hostingu, ne jen v MaxAuth.

/maxauth spawnset nefunguje

Příkaz musí spustit hráč, který je připojený na backend server s MaxAuth backend pluginem. Proxy pak pošle backendu požadavek na uložení aktuální pozice.

Doporučený minimální setup

Proxy:

storageType: MYSQL
limboServerNames: [limbo]
mainServerNames: [lobby]
afterRegisterRedirect: true
afterLoginRedirect: true
verifyCaptchaCode: false
confirmPassword: true
registerPremiumUsers: true

Backend:

accessToken: 'stejny-token-jako-na-proxy'
accessTokenDisabled: false
restrictedMovement: true
restrictedInteractions: true
blindnessEffect: true
setPlayerTime: day
setPlayerWeather: clear

Messages:

prefix: '{#55ff55}M{#55ff8e}a{#55ffc6}x{#55ffff}A{#71e3e3}u{#8ec6c6}t{#aaaaaa}h '

Autor

MaxAuth by DjDevs.eu.

Clone this wiki locally