?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
Z-Auth

Z-Auth

Professional Minecraft authentication plugin for Paper 1.21.1+ and the wider 1.21.x line

5
0
5
0

Compatibility

Minecraft: Java Edition

1.21.x

Platforms

Links

Report issues View source Visit wiki Join Discord server
Donate on PayPal

Tags

Creators

Details

Published 2 days ago

Z-auth_banner

Auth

Auth is a proxy-first authentication system for Minecraft networks. It uses one proxy plugin for Velocity/BungeeCord and lightweight backend guard plugins for Spigot/Paper/Purpur/Folia servers.

Players authenticate on the proxy with /login or /register, while backend servers stay protected until the proxy confirms the player is logged in.

Addon Required - Link

Features

Feature Status
Velocity support Yes
BungeeCord support Yes
Spigot backend guard Yes
Paper/Purpur backend guard Yes
Folia backend guard Yes
SQLite database Yes
MySQL / MariaDB / PostgreSQL Yes
/login and /register Yes
Session login Yes
Authenticator 2FA Yes
Admin /zauth commands Yes
Backend movement/chat/command protection Yes
Backend inventory/drop/damage protection Yes
Config auto-merge on update Yes
bStats support Yes

Downloads

Auth builds multiple jars. Install the correct jar for each server type.

Jar Install on
Auth-Proxy-<version>.jar Velocity or BungeeCord proxy
Auth-Backend-SpigotLegacy-<version>.jar Spigot-style 1.16-1.19 backends
Auth-Backend-Spigot-<version>.jar Spigot-style 1.20-1.21 backends
Auth-Backend-Paper-<version>.jar Paper/Purpur 1.21+ backends
Auth-Backend-Folia-<version>.jar Folia 1.21+ backends

Do not install the proxy jar on backend servers.
Do not install backend jars on the proxy.

How It Works

  1. A player joins the proxy.
  2. Auth checks whether the player is registered.
  3. The player logs in, registers, or verifies 2FA.
  4. The proxy sends the authenticated state to backend servers.
  5. Backend servers block gameplay until the proxy confirms login.

The backend and proxy communicate automatically over:

zcraftauth:state

No backend database setup is required.

Commands

Command Description
/login <password> Log into your account
/l <password> Login alias
/register <password> <password> Register a new account
/reg <password> <password> Register alias
/logout Log out and lock backend access again
/changepass <old> <new> Change your password
/2fa enable Generate an authenticator secret
/2fa verify <code> Verify your 2FA login
/2fa disable <code> Disable authenticator 2FA

Admin Commands

/zauth requires:

zcraftauth.admin
Command Description
/zauth status Show authenticated player count
/zauth unregister <player> Delete a player login
/zauth setpassword <player> <password> Change a player password
/zauth disable2fa <player> Remove a player's 2FA
/zauth forcelogin <player> Mark a player as logged in
/zauth logout <player> Mark a player as logged out

Database Support

Auth supports:

  • SQLite
  • MySQL
  • MariaDB
  • PostgreSQL

Default config:

database:
  type: sqlite

  sqlite:
    file: auth.db

External database example:

database:
  type: mysql

  external:
    host: localhost
    port: 3306
    database: zcraft_auth
    username: root
    password: ""
    ssl: false

Session Login

Auth can restore a player session when their IP matches the last known login IP.

session:
  enabled: true

This helps avoid unnecessary re-logins while keeping backend servers protected.

Timeouts

Login and register timeouts are separate.

general:
  login-timeout: 0
  register-timeout: 0

Set either value to 0 to disable that timeout.

Backend Protection

The backend plugin is intentionally small and low-impact. It does not connect to the database and does not run repeating tasks.

It can block:

  • Movement
  • Chat
  • Commands
  • Inventory clicks
  • Item drops
  • Item pickup
  • Damage
  • Attacking

Backend config:

block-movement: true
allow-chat: false
enable-bypass-permission: false

allowed-commands:
  - "/login"
  - "/register"
  - "/l"
  - "/reg"
  - "/2fa"
  - "/totp"
  - "/authenticator"

Operators are not bypassed by default.

2FA Authenticator

Players can enable authenticator-based 2FA:

/2fa enable

On future logins, after entering the correct password, they must verify:

/2fa verify <code>

Compatible with common authenticator apps such as Google Authenticator, Authy, 2FAS, and similar TOTP apps.

Performance

Auth is designed to stay light on backend servers:

  • Backend plugin has no database connection.
  • Backend plugin does not hash passwords.
  • Backend plugin does not perform account lookups.
  • Backend plugin only listens for protection events and proxy state.
  • Proxy database operations run asynchronously.
  • Prompt bars are event-driven.

This keeps backend TPS/MSPT impact minimal.

Currently Not Ported

The older Paper-only codebase contained more planned or legacy systems. These are not yet fully ported into the current proxy-first system:

  • E-mail recovery and confirmation
  • Country whitelist/blacklist
  • Built-in proxy AntiBot
  • Premium Mojang bypass
  • Custom external table/column mapping
  • Legacy hash import/migration formats
  • Editable per-language message packs
  • Automatic database backups
  • Account importers

These are planned candidates for future proxy-side implementation.

Requirements

Component Supported
Java 21+
Proxy Velocity, BungeeCord
Backend Spigot-style, Paper, Purpur, Folia
Minecraft Backend variants for 1.16-1.19, 1.20-1.21, and 1.21+ families

Installation

  1. Install Auth-Proxy-<version>.jar on your proxy.
  2. Install the matching Auth-Backend-<version>.jar on each backend server.
  3. Start the proxy once to generate the config.
  4. Edit the proxy config if needed.
  5. Restart the proxy and backend servers.
  6. Join and register with:
/register <password> <password>

Support

If something does not work, include:

  • Proxy type and version
  • Backend server type and version
  • Auth proxy jar name
  • Auth backend jar name
  • Console error logs
  • Config database type