Home

MaxAuth Wiki

MaxAuth is a proxy-first authentication plugin for Minecraft networks. It protects cracked accounts with passwords, supports premium players, manages UUIDs, sessions, two-factor authentication, captcha maps, backend protection, and safe migration from JPremium.

MaxAuth is designed as a modern successor to JPremium. It keeps the core authentication ideas and migration path familiar for existing JPremium networks, while adding MaxAuth-specific configuration, messages, backend protections, diagnostics, and audit tooling.

MaxAuth has two parts:

Proxy plugin for Velocity or BungeeCord.
Backend plugin for Paper/Spigot servers behind the proxy.

The proxy plugin is the main authority. It decides whether a player is premium, cracked, or Bedrock, which UUID they should use, whether they are authenticated, where they should be redirected, and which profile is stored in the database.

The backend plugin protects players during authorization. It can restrict movement, interactions, chat, commands, inventory, show a captcha map, lock player time/weather, move players to an auth spawn, and verify that state updates really came from the trusted proxy.

Supported Platforms
Core Concept
Installation
Proxy Configuration
Backend Configuration
Player Commands
Admin Commands
Permissions
Authentication Flow
Two-Factor Authentication
Captcha
Limbo and Main Servers
Messages
Automatic File Updates
Database
JPremium Migration
Backend Security
Troubleshooting
Recommended Minimal Setup

Supported Platforms

Proxy:

Velocity
BungeeCord

Backend:

Paper
Spigot

Databases:

SQLite
MySQL
MariaDB
PostgreSQL

Java:

Java 17+

Optional backend plugins:

ProtocolLib
BungeeGuard
PlaceholderAPI

Core Concept

MaxAuth works as a proxy-first authentication system.

A player connects to the proxy. The proxy detects the account type, loads or creates the player profile, and decides whether the player can go straight to a main server or must first go to a limbo server to register or log in.

Unauthenticated cracked players are sent to a limbo server. The backend plugin keeps them restricted until they authenticate. After a successful login or registration, the proxy sends the new auth state to the backend and optionally redirects the player to a main server.

Premium players are verified through the Mojang resolver and can be logged in automatically. Bedrock players can be handled through Floodgate/Geyser support when enabled.

Installation

Proxy

Put the MaxAuth jar into the proxy plugins folder:

velocity/plugins/

or:

bungee/plugins/

On first startup, MaxAuth generates the proxy configuration. If the plugin detects that required configuration is still missing, it prints a large warning in the console and shuts the proxy down. This prevents players from joining without auth and UUID protection.

Backend

Put the same jar into every backend server:

plugins/

On first install, the backend prints a warning that the config should be configured.

Access Token

Proxy and backend must use the same token:

accessToken: 'long-random-token'

The token verifies plugin-message communication between proxy and backend. Use a long, random, private value.

Proxy Configuration

The proxy config contains the main MaxAuth settings.

Storage type:

storageType: SQLITE

Supported values:

SQLITE
MYSQL
MARIADB
POSTGRESQL

Database table name:

storageTableName: maxauth_users

MySQL/MariaDB/PostgreSQL settings:

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

Connection pool:

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

If the database reports Too many connections, lower mainly:

connectionPoolSize: 3
connectionPoolIdle: 1

Limbo and main servers:

limboServerNames: [limbo]
mainServerNames: [main]

Redirects after authorization:

afterRegisterRedirect: true
afterLoginRedirect: true

When redirects are enabled, login/register success messages are shown after the player reaches a main server. When disabled, the success message is shown immediately on the current server.

Premium account handling:

registerPremiumUsers: true
detectPremiumUniqueIdsInHandshake: true
secondLoginCracked: false

UUID mode:

uniqueIdsType: REAL

Supported values:

REAL
OFFLINE
FIXED

Do not change UUID mode after players are registered unless you are intentionally migrating data.

Captcha:

verifyCaptchaCode: false

Captcha is enabled or disabled only on the proxy. The backend config only controls the captcha map slot.

Passwords:

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

Configurable algorithms for new passwords:

ARGON2ID - recommended for new installations.
BCRYPT - recommended when you want a widely compatible modern hash.
PBKDF2_SHA256
PBKDF2_SHA512
SALTEDSHA512
SHA256 - MaxAuth salted SHA-256, kept for compatibility with existing configs.
SHA512 - MaxAuth salted SHA-512, kept for compatibility with existing configs.

SHA256 and SHA512 are salted MaxAuth hashes. Classic unsalted SHA hashes are accepted only for migration as CSHA256 and CSHA512.

Stored password hashes include the algorithm prefix, so MaxAuth can still verify older hashes after changing passwordHashingAlgorithm.

rehashPasswordWhenUsingDifferentAlgorithm: true

When enabled, MaxAuth re-hashes the player's password after a successful login if the stored hash uses a different algorithm than the current configuration. This is useful when migrating existing accounts to ARGON2ID or BCRYPT.

Migration-only algorithms accepted from the database:

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

These migration-only algorithms are accepted for verification only. They should not be used for new registrations.

Sessions:

manuallySessionTime: 720
automaticSessionTime: 10

Login protection:

maximumLoginTriesBeforeDisconnection: 5
addressBanDuration: 10
maximumAuthorisationTime: 90

Email recovery:

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

When emailEnabled: false, email reminder messages are not sent, and /changeemailaddress, /requestpasswordrecovery, /confirmpasswordrecovery, and the matching /maxauth admin subcommands are disabled.

mailEncryption controls how MaxAuth connects to the SMTP server:

NONE for plain SMTP.
STARTTLS for SMTP servers that upgrade the connection, commonly port 587.
SSL for implicit TLS SMTP servers, commonly port 465.

mailUseTLS is kept only as a compatibility fallback for older configs. New setups should use mailEncryption.

Two-factor authentication:

secondFactorEnabled: true

When secondFactorEnabled: false, 2FA reminder messages are not sent, existing 2FA tokens are ignored during login, and /requestsecondfactor, /activatesecondfactor, /deactivatesecondfactor, and the matching /maxauth admin subcommands are disabled.

Discord audit webhooks:

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

You can define multiple webhooks and route different audit categories to different Discord channels.

Backend Configuration

The backend config controls player restrictions and backend protection.

Access token:

accessToken: 'same-token-as-proxy'
accessTokenDisabled: false

Only set accessTokenDisabled: true when the backend is protected in another way, for example by a firewall, BungeeGuard, or Velocity modern forwarding.

Trusted proxy IPs:

trustedProxyIps: []

An empty list means the backend only checks the MaxAuth token. Exact IPs and CIDR ranges are supported, for example ['127.0.0.1', '10.0.0.0/8'].

Captcha map:

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

captchaMapSlot is slot 1-9.

Unauthenticated-player protection:

restrictedMovement: true
restrictedInteractions: true
blindnessEffect: true

Player time and weather during authorization:

setPlayerTime: day
setPlayerWeather: clear

Supported time examples:

day
noon
night
midnight
18:15
1000

Supported weather values:

clear
rain
thunder

Empty values disable the feature:

setPlayerTime: ''
setPlayerWeather: ''

Spawn location:

spawnLocation: ''

Set it in game with:

/maxauth spawnset

The command is executed on the proxy, but the player must be connected to a backend server running the MaxAuth backend plugin. The backend stores the current player location including yaw and pitch.

Player Commands

Login and Registration

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

/login <password> <code> is used when 2FA is enabled for the account.

The /register format depends on:

confirmPassword
verifyCaptchaCode

Sessions

/startsession
/destroysession

/startsession creates a manual session. The player can then be logged in automatically on the next join from the same address.

/destroysession removes the session.

Passwords

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

The repeated-password variant depends on confirmPassword.

Account

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

When riskyCommandsConfirmation is enabled, risky actions require /confirm.

Email Recovery

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

Recovery works only with correctly configured SMTP settings in the proxy config. Player recovery commands are available only during the login phase, before the player logs in. This prevents already authenticated players from starting or confirming recovery from an active session.

If confirmPassword is enabled, /confirmpasswordrecovery requires the repeated password:

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

Two-Factor Authentication

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

Flow:

The player logs in normally.
The player runs /requestsecondfactor.
MaxAuth sends a clickable QR link.
The player scans the QR code in a TOTP app.
The player activates 2FA with /activatesecondfactor <password> <code>.
Future logins use /login <password> <code>.

Admin Commands

Admin commands are available under:

/maxauth
/mauth

Basic commands:

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

/maxauth testmail <email> sends a diagnostic recovery email using the executor's current nickname placeholder and recovery code 123456. It reports the SMTP host, port, encryption mode, elapsed send time, and success or failure status in chat.

Profile lookup and management:

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

Account actions:

/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 and 2FA:

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

Admin commands resolve profiles by nickname or UUID. Some commands tab-complete online player names.

Permissions

maxauth.admin

Allows using admin commands under /maxauth and /mauth.

maxauth.command.reload

Allows reload through /maxauth reload or the reload command.

The backend plugin also uses:

maxauth.admin

This permission defaults to OP.

Authentication Flow

New Cracked Player

The player connects to the proxy.
The proxy creates a cracked profile.
The player is sent to a limbo server.
The backend restricts the player according to the backend config.
The player uses /register.
The proxy stores the password and marks the player as logged in.
The backend receives the new player state.
The player is redirected to a main server according to config.

Registered Cracked Player

The player connects.
The proxy loads the profile from the database.
If the player has a valid session, MaxAuth logs them in automatically.
If there is no valid session, the player is sent to limbo.
The player uses /login.
After success, the player is redirected to a main server.

Premium Player

The proxy verifies the nickname through Mojang.
The player receives an online UUID.
Depending on config, the profile is created automatically.
The player is logged in without a password.

Bedrock Player

Bedrock behavior depends on:

floodgateSupport:
  enabled: true
  useApiVerification: true

When enabled, MaxAuth adjusts UUID and behavior for Floodgate/Geyser players. API verification uses Floodgate API when available for more accurate detection, especially linked Bedrock-Java accounts.

Two-Factor Authentication

2FA uses TOTP codes from apps such as Google Authenticator, Authy, or Aegis.

Enable:

/requestsecondfactor
/activatesecondfactor <password> <code>

Disable:

/deactivatesecondfactor <password> <code>

Login with enabled 2FA:

/login <password> <code>

Wrong 2FA codes behave similarly to wrong passwords and count as failed login attempts.

2FA is intended for cracked/password accounts. Premium and Bedrock accounts currently do not use it.

The entire 2FA feature can be disabled with:

secondFactorEnabled: false

Captcha

Captcha is enabled on the proxy:

verifyCaptchaCode: true

The backend config controls the map slot:

captchaMapSlot: 1

When captcha is enabled, a new unregistered player receives a captcha map and must use the correct register command based on the config, for example:

/register <password> <captcha>

or:

/register <password> <password> <captcha>

Limbo and Main Servers

limboServerNames are servers for unauthenticated players:

limboServerNames: [limbo]

mainServerNames are servers for authenticated players:

mainServerNames: [main]

Multiple servers can be configured:

mainServerNames: [lobby, survival, skyblock]

Multiple entries work as fallbacks. If the first server is unavailable, MaxAuth can use another available server from the list.

Messages

Proxy messages are stored in:

plugins/maxauth/messages.yml

Supported message types:

chat
title
subtitle
actionbar
bossbar
kickscreen

Every message key has a type comment:

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 '

Colors:

&aGreen text
{#55ff55}Hex text

Gradient:

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

Multi-line messages:

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

Register variants:

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

Variant order:

confirmPassword=false, verifyCaptchaCode=false
confirmPassword=true, verifyCaptchaCode=false
confirmPassword=false, verifyCaptchaCode=true
confirmPassword=true, verifyCaptchaCode=true

Automatic File Updates

MaxAuth can automatically prepend new settings into existing files.

This applies to:

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

When a new setting is added in an update, MaxAuth adds it to the top of the existing file together with comments from the default resource.

Database

SQLite is the simplest option for testing or small servers.

For larger networks, use:

MySQL
MariaDB
PostgreSQL

MySQL example:

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

On hosts with low connection limits, use a smaller pool:

connectionPoolSize: 3
connectionPoolIdle: 1

JPremium Migration

MaxAuth can migrate data from the original JPremium SQL table user_profiles.

This is intended for networks that are replacing JPremium with MaxAuth and want to keep existing registered accounts, premium UUID links, password hashes, email addresses, sessions, addresses, and timestamps where the old table contains them.

On proxy startup, MaxAuth checks the current database. If the table user_profiles exists and the target MaxAuth table is different, for example maxauth_users, MaxAuth creates or updates:

plugins/maxauth/migrate_DB.yml

The file contains a pre-report with counts:

legacyAccounts - number of rows in the old JPremium table.
existingMaxAuthAccounts - number of accounts in the target MaxAuth table.
accountsToMigrate - number of rows that can be migrated.
collisionRowsToSkip - number of rows skipped because of a collision.
collisionsByUniqueId - UUID collisions.
collisionsByPremiumId - premium UUID collisions.
collisionsByNickname - last nickname collisions.
missingRequiredColumns - missing columns if the old table is not compatible.

Migration is manually confirmed. The generated file initially contains:

migrateAfterRestart: false

After reviewing the report, set:

migrateAfterRestart: true

Then restart the proxy. MaxAuth migrates the data into the current table. If an account already exists in MaxAuth by uniqueId, premiumId, or lastNickname, the existing MaxAuth profile wins and the JPremium row is skipped.

After a successful migration, MaxAuth:

removes migrateAfterRestart,
writes finalReport,
renames the old user_profiles table to user_profiles_old.

If user_profiles_old already exists, MaxAuth uses a timestamped table name so older backups are not overwritten.

Migration uses the same database configuration as MaxAuth. The JPremium table must therefore be in the same database as the target MaxAuth table.

Backend Security

Backend servers should not be directly reachable from the public internet.

Recommended setup:

Allow backend access only from proxy IPs.
Use a firewall.
Use Velocity modern forwarding or BungeeGuard.
Use a long random accessToken.
Keep accessTokenDisabled: false unless you are completely sure the backend is protected another way.

If the MaxAuth proxy part fails to start correctly, the plugin shuts down the proxy. This protects the network from players entering with wrong UUIDs or unprotected auth state.

Troubleshooting

Player Does Not See Success Message After Login/Register

Check:

afterLoginRedirect: true
afterRegisterRedirect: true

If redirect is enabled, the success message is shown after the player reaches a main server. If redirect is disabled, it is shown immediately on the limbo/current server.

Captcha Appears Even Though It Should Be Disabled

Captcha is disabled on the proxy:

verifyCaptchaCode: false

Backend captchaMapSlot controls only the slot.

Database Reports Too Many Connections

Lower the connection pool:

connectionPoolSize: 3
connectionPoolIdle: 1

If phpMyAdmin cannot connect either, the issue is in the database/hosting, not only in MaxAuth.

`/maxauth spawnset` Does Not Work

The command must be executed by a player connected to a backend server running the MaxAuth backend plugin. The proxy sends the backend a request to save the current player position.

Recommended Minimal Setup

Proxy:

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

Backend:

accessToken: 'same-token-as-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 '

Author

MaxAuth by DjDevs.eu.

Home

MaxAuth Wiki

Table of Contents

Supported Platforms

Core Concept

Installation

Proxy

Backend

Access Token

Proxy Configuration

Backend Configuration

Player Commands

Login and Registration

Sessions

Passwords

Account

Email Recovery

Two-Factor Authentication

Admin Commands

Permissions

Authentication Flow

New Cracked Player

Registered Cracked Player

Premium Player

Bedrock Player

Two-Factor Authentication

Captcha

Limbo and Main Servers

Messages

Automatic File Updates

Database

JPremium Migration

Backend Security

Troubleshooting

Player Does Not See Success Message After Login/Register

Captcha Appears Even Though It Should Be Disabled

Database Reports Too Many Connections

/maxauth spawnset Does Not Work

Recommended Minimal Setup

Author

Uh oh!

Clone this wiki locally

`/maxauth spawnset` Does Not Work