IPAuth

IPAuth

IPAuth is a lightweight, mod that protects Minecraft player accounts by binding each authorized account to its first connecting IP address.

It is designed primarily for private and offline-mode servers..

Features

• Built-in UUID-based whitelist
• Automatic IP binding on the first authorized connection
• Blocks connections from an unexpected IP address
• Supports normalized IPv4 and IPv6 addresses
• Clear, configurable disconnect messages
• Designed with offline-mode servers in mind
• Uses exact offline UUID generation based on player names
• Masked IP addresses in routine server logs

How It Works

1. An administrator adds a player to the IPAuth whitelist (if enabled).
2. The player connects to the server for the first time.
3. IPAuth stores the player’s UUID, name, and current IP address.
4. Future connections must use the same UUID and IP address.
5. If the IP address does not match, the connection is rejected before the player enters the world.
6. An administrator can reset the binding when the player’s IP changes.

A whitelist entry and an IP binding are separate. A player must be whitelisted first, and their IP is then registered during their first successful connection.

Commands

IPAuth replaces the standard /whitelist command with its own whitelist implementation.

| Command | Description |
|—|—|
| /whitelist on | Enables the IPAuth whitelist |
| /whitelist off | Disables the IPAuth whitelist |
| /whitelist add <player> | Adds a player to the whitelist |
| /whitelist remove <player> | Removes a player from the whitelist |
| /whitelist list | Lists all authorized players |
| /ipauth ip check <player> | Displays the player’s current IP binding status |
| /ipauth ip reset <player> | Removes the stored IP binding |
| /ipauth status | Displays the current IPAuth status and entry counts |
| /ipauth reload | Reloads the configuration and messages |
| /ipauth help | Displays the available IPAuth commands |

Example Setup

Add a player and enable the whitelist:

whitelist on
whitelist add Lukys

Check whether the player has a registered IP address:

ipauth ip check Lukys

If the player’s public IP changes, reset the old binding:

ipauth ip reset Lukys

The player’s new IP address will be registered during their next authorized connection.

Configuration and Data

IPAuth stores its files in:

config/ipauth/

The directory contains:

• config.json – settings and customizable messages
• ipdata.json – UUID and IP bindings
• whitelist.json – authorized players

Planned Features

Traditional /register, /login, and similar authentication commands may be added in the future, but they are not currently a priority. If you would like to see them implemented sooner, let me know on Discord.

Important Notes

IPAuth is intended as an additional protection layer, especially for offline-mode servers. It is not a replacement for properly secured online-mode authentication.

Players may need their IP binding reset when they:

• receive a new IP address,
• switch between home internet and mobile data,
• connect through a VPN,
• move to another network,
• change their exact name on an offline-mode server.

IP addresses can be personal data. Server administrators are responsible for informing players and handling stored data according to applicable privacy laws.