ChunkifyAuth -----
Secure and simple authentication system for your Minecraft server.# ChunkifyAuth - Complete Documentation (BBCode)
---
## Table of Contents
---
## 1️⃣ Installation & Setup
### Prerequisites
### Installation Steps
Step 1: Download
Step 2: Initial Configuration
Step 3: Verify Installation
---
## 2️⃣ Quick Start Guide
### For Server Administrators
First Steps:
1. Install plugin and restart server
2. Edit config.yml:
- Choose storage type (mysql or json)
- Set authentication requirements
- Configure security settings
3. Restart server again
4. Test with: /login test
### For Players
Getting Started:
1. Join server for first time
2. Type: /register password password
3. Login with: /login password
4. You're authenticated!
5. Logout with: /logout
---
## 3️⃣ Authentication System
### Login Flow
Player Joins
↓
Check if Authenticated
├─ Yes → Allow Full Access
└─ No → Block Actions (chat, blocks, etc)
↓
Player Runs /login
↓
Verify Password with Cache
├─ Hit → Return Result (< 1ms)
└─ Miss → Query Database
↓
Check against BCrypt Hash
├─ Match → Create Session
└─ No Match → Fail & Track Attempt
↓
Check Rate Limiting
├─ Allowed → Session Active
└─ Blocked → Lockout Applied
### Account Registration
Player Runs /register pass1 pass2
↓
Validate Password Strength
├─ Valid → Continue
└─ Invalid → Show Error
↓
Check Username Availability
├─ Available → Continue
└─ Exists → Show Error
↓
Hash Password with BCrypt
↓
Store in Database
↓
Create Session
↓
Player Authenticated ✓
---
## 4️⃣ Security Features
### Password Security
BCrypt Encryption
Password Requirements
### Brute Force Protection
Rate Limiting
Exponential Backoff
### Account Lockout
Automatic Lockout
Admin Unlock
/authAdmin unlock <player>
---
## 5️⃣ Configuration Guide
### config.yml Structure
Section: authentication
authentication:
enableCache: true # Enable login caching
enableAuditLog: true # Log all events
enableSecurityFeatures: true # Enable rate limiting
preventChat: true # Block chat if not logged in
preventBlockBreak: true # Block mining if not logged in
preventBlockPlace: true # Block building if not logged in
preventDamage: true # Block combat if not logged in
preventItemDrop: true # Block item drop if not logged in
bypassPermission: "chunkifyauth.bypass" # Permission to skip auth
Section: passwords
passwords:
bcryptCost: 10 # 4=fast, 31=slow/secure
minLength: 8
requireSpecialChars: false
autoMigrateHash: true # Rehash old passwords
promptUserRehash: false # Ask user before rehash
Section: security
security:
maxLoginAttempts: 5 # Before lockout
lockoutDurationMinutes: 30
exponentialBackoffEnabled: true
ipBasedBlockingEnabled: true
Section: storage
storage:
type: "json" # "json" or "mysql"
mysql:
host: localhost
port: 3306
database: chunkifyauth
username: root
password: password
maxConnections: 10
connectionTimeoutMs: 5000
retryCount: 3
retryDelayMs: 1000
healthCheckIntervalSeconds: 60
Section: cache
cache:
maxCacheSize: 10000 # Max entries
defaultTTLSeconds: 3600 # 1 hour
cleanupIntervalSeconds: 600 # 10 minutes
enableCache: true
enableAutoCleanup: true
evictionPolicy: "LRU" # Least Recently Used
Section: audit
audit:
enableAuditLog: true
logFilePath: "plugins/ChunkifyAuth/audit.log"
rotationIntervalDays: 30
compressOldLogs: true
retentionDays: 90
Section: language
language: "en" # "en" for English, "es" for Spanish
---
## 6️⃣ Commands Reference
### Player Commands
/login <password>
/register <password> <confirm>
/logout
### Admin Commands
/authAdmin unlock <player>
/authAdmin stats
/authAdmin audit <player>
/authAdmin cache
/authAdmin security
/authAdmin config
/authReload
/unregister <player>
---
## 7️⃣ Database Setup
### JSON Storage (Default)
Automatic Setup
File Location
plugins/
└── ChunkifyAuth/
├── config.yml
├── data.json
└── audit.log
### MySQL Setup
Prerequisites
Create Database
CREATE DATABASE chunkifyauth;
CREATE USER 'chunkifyauth'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON chunkifyauth.* TO 'chunkifyauth'@'localhost';
FLUSH PRIVILEGES;
Configure Plugin
storage:
type: "mysql"
mysql:
host: localhost
port: 3306
database: chunkifyauth
username: chunkifyauth
password: password
Tables Created Automatically
---
## 8️⃣ Multi-Language Support
### Available Languages
### Changing Language
config.yml
# Set to "en" for English or "es" for Spanish
language: "es"
### Custom Messages
Messages are loaded from files:
Edit these files to customize messages.
### Supported Placeholders
---
## 9️⃣ Version Compatibility
### Supported Versions
### Server Types
Tested on:
### Automatic Version Detection
Plugin automatically detects your server version and adapts:
---
## Troubleshooting
### Plugin Won't Load
Check server version
Check Java version
Check logs
### Database Connection Failed
Verify MySQL is running
mysql -h localhost -u chunkifyauth -p
Check credentials
Test connectivity
### Players Can't Login
Check password
Check account exists
/authAdmin audit <player>
Check if locked out
### Performance Issues
Check cache settings
cache:
maxCacheSize: 10000
enableAutoCleanup: true
Monitor statistics
/authAdmin cache # Check hit ratio
/authAdmin stats # Check authentication counts
Database optimization
---
## 1️⃣1️⃣ Performance Tuning
### Cache Optimization
For Small Servers (< 100 players)
cache:
maxCacheSize: 1000
defaultTTLSeconds: 1800
cleanupIntervalSeconds: 300
For Medium Servers (100-500 players)
cache:
maxCacheSize: 5000
defaultTTLSeconds: 3600
cleanupIntervalSeconds: 600
For Large Servers (500+ players)
cache:
maxCacheSize: 50000
defaultTTLSeconds: 7200
cleanupIntervalSeconds: 1800
### Database Optimization
Connection Pool Settings
mysql:
maxConnections: 5 # Small server
maxConnections: 20 # Medium server
maxConnections: 50 # Large server
connectionTimeoutMs: 5000
retryCount: 3
### BCrypt Cost Tuning
For Performance (Faster)
passwords:
bcryptCost: 6 # Fast login (< 10ms)
For Security (Slower)
passwords:
bcryptCost: 12 # Secure but slower (100-200ms)
---
## 1️⃣2️⃣ API Reference
### For Plugin Developers
Get ChunkifyAuth Instance
ChunkifyAuth plugin = (ChunkifyAuth)
Bukkit.getPluginManager().getPlugin("ChunkifyAuth");
if (plugin != null && plugin.isEnabled()) {
// Use API
}
Check Player Authenticated
SessionManager sessions = plugin.getSessionManager();
if (sessions.hasActiveSession(player)) {
// Player is logged in
}
Get Version Info
import com.chunkify.auth.compat.VersionCompat;
String version = VersionCompat.getVersionString(); // "1.20.4"
if (VersionCompat.isSupported()) {
// Version compatible
}
Send Messages
import com.chunkify.auth.compat.ChatCompat;
ChatCompat.sendMessage(player, "&cError: &aSystem");
ChatCompat.sendTitle(player, "&cTitle", "&aSubtitle", 10, 20, 10);
---
## Support
### Getting Help
### Reporting Issues
Include:
---
---
ChunkifyAuth v1.2.0
Complete Documentation & Administration Guide
Complete Documentation & Administration Guide
---
## Table of Contents
- Installation & Setup
- Quick Start Guide
- Authentication System
- Security Features
- Configuration Guide
- Commands Reference
- Database Setup
- Multi-Language Support
- Version Compatibility
- Troubleshooting
- Performance Tuning
- API Reference
---
## 1️⃣ Installation & Setup
### Prerequisites
- Minecraft Server 1.16.5 or higher
- Java 8 or higher
- Spigot, Paper, Purpur, or compatible server
- 100MB disk space minimum
### Installation Steps
Step 1: Download
- Download ChunkifyAuth-1.2.0.jar
- Place in plugins/ folder
- Restart server or use /reload
Step 2: Initial Configuration
- Server will generate config.yml automatically
- Edit config.yml to customize settings
- Adjust database connection (if using MySQL)
- Restart server again to apply changes
Step 3: Verify Installation
- Check server logs for [ChunkifyAuth] message
- Should see: "ChunkifyAuth v1.2.0 Enabled"
- Look for: "Minecraft Version: X.Y.Z"
- Type /authAdmin help to verify commands work
---
## 2️⃣ Quick Start Guide
### For Server Administrators
First Steps:
Code (Text):
1. Install plugin and restart server
2. Edit config.yml:
- Choose storage type (mysql or json)
- Set authentication requirements
- Configure security settings
3. Restart server again
4. Test with: /login test
Getting Started:
Code (Text):
1. Join server for first time
2. Type: /register password password
3. Login with: /login password
4. You're authenticated!
5. Logout with: /logout
## 3️⃣ Authentication System
### Login Flow
Code (Text):
Player Joins
↓
Check if Authenticated
├─ Yes → Allow Full Access
└─ No → Block Actions (chat, blocks, etc)
↓
Player Runs /login
↓
Verify Password with Cache
├─ Hit → Return Result (< 1ms)
└─ Miss → Query Database
↓
Check against BCrypt Hash
├─ Match → Create Session
└─ No Match → Fail & Track Attempt
↓
Check Rate Limiting
├─ Allowed → Session Active
└─ Blocked → Lockout Applied
Code (Text):
Player Runs /register pass1 pass2
↓
Validate Password Strength
├─ Valid → Continue
└─ Invalid → Show Error
↓
Check Username Availability
├─ Available → Continue
└─ Exists → Show Error
↓
Hash Password with BCrypt
↓
Store in Database
↓
Create Session
↓
Player Authenticated ✓
## 4️⃣ Security Features
### Password Security
BCrypt Encryption
- Cost factor: 4-31 (default 10)
- Higher = more secure but slower
- Recommended: 10-12 for balance
- Each password unique with salt
Password Requirements
- Minimum length: 8 characters
- Special characters: Optional (configurable)
- Spaces not allowed
- Case sensitive
### Brute Force Protection
Rate Limiting
- Track failed attempts per player
- Track failed attempts per IP
- Configurable max attempts (default 5)
- Lockout duration: 30 minutes (configurable)
Exponential Backoff
- 1st failure: 1 second wait
- 2nd failure: 2 seconds wait
- 3rd failure: 4 seconds wait
- 4th failure: 8 seconds wait
- 5th failure: Account locked
### Account Lockout
Automatic Lockout
- After configurable failed attempts
- Duration: Configurable (default 30 min)
- Admin can unlock manually
- IP-based blocking available
Admin Unlock
Code (Text):
/authAdmin unlock <player>
## 5️⃣ Configuration Guide
### config.yml Structure
Section: authentication
Code (Text):
authentication:
enableCache: true # Enable login caching
enableAuditLog: true # Log all events
enableSecurityFeatures: true # Enable rate limiting
preventChat: true # Block chat if not logged in
preventBlockBreak: true # Block mining if not logged in
preventBlockPlace: true # Block building if not logged in
preventDamage: true # Block combat if not logged in
preventItemDrop: true # Block item drop if not logged in
bypassPermission: "chunkifyauth.bypass" # Permission to skip auth
Code (Text):
passwords:
bcryptCost: 10 # 4=fast, 31=slow/secure
minLength: 8
requireSpecialChars: false
autoMigrateHash: true # Rehash old passwords
promptUserRehash: false # Ask user before rehash
Code (Text):
security:
maxLoginAttempts: 5 # Before lockout
lockoutDurationMinutes: 30
exponentialBackoffEnabled: true
ipBasedBlockingEnabled: true
Code (Text):
storage:
type: "json" # "json" or "mysql"
mysql:
host: localhost
port: 3306
database: chunkifyauth
username: root
password: password
maxConnections: 10
connectionTimeoutMs: 5000
retryCount: 3
retryDelayMs: 1000
healthCheckIntervalSeconds: 60
Code (Text):
cache:
maxCacheSize: 10000 # Max entries
defaultTTLSeconds: 3600 # 1 hour
cleanupIntervalSeconds: 600 # 10 minutes
enableCache: true
enableAutoCleanup: true
evictionPolicy: "LRU" # Least Recently Used
Code (Text):
audit:
enableAuditLog: true
logFilePath: "plugins/ChunkifyAuth/audit.log"
rotationIntervalDays: 30
compressOldLogs: true
retentionDays: 90
Code (Text):
language: "en" # "en" for English, "es" for Spanish
## 6️⃣ Commands Reference
### Player Commands
/login <password>
- Authenticate with password
- Usage: /login mypassword123
- Response: Success or error message
- Cooldown: Applied if rate limited
/register <password> <confirm>
- Create new account
- Usage: /register mypass123 mypass123
- Passwords must match
- Passwords must meet strength requirements
- One account per player UUID
/logout
- End current session
- Unauthenticates the player
- Blocks chat/blocks/combat until re-login
### Admin Commands
/authAdmin unlock <player>
- Unlock player account after lockout
- Permission: chunkifyauth.admin
- Usage: /authAdmin unlock PlayerName
/authAdmin stats
- View authentication statistics
- Shows: logins, failures, active sessions
- Permission: chunkifyauth.admin
/authAdmin audit <player>
- View audit log for player
- Shows: all login attempts, IPs, times
- Permission: chunkifyauth.admin
/authAdmin cache
- View cache statistics
- Shows: hits, misses, size, hit ratio
- Permission: chunkifyauth.admin
/authAdmin security
- View security statistics
- Shows: locked accounts, threats
- Permission: chunkifyauth.admin
/authAdmin config
- View current configuration
- Permission: chunkifyauth.admin
/authReload
- Reload configuration from disk
- Permission: chunkifyauth.admin
- Usage: /authReload
- Note: Will reconnect database if needed
/unregister <player>
- Delete player account (admin only)
- Permission: chunkifyauth.admin
- Warning: This cannot be undone
---
## 7️⃣ Database Setup
### JSON Storage (Default)
Automatic Setup
- No configuration required
- Works out of the box
- Stores in plugins/ChunkifyAuth/data.json
- Suitable for small servers (< 1000 players)
File Location
Code (Text):
plugins/
└── ChunkifyAuth/
├── config.yml
├── data.json
└── audit.log
Prerequisites
- MySQL 5.7+ or MariaDB 10.2+
- Database created
- User with database privileges
- Network access to database
Create Database
Code (Text):
CREATE DATABASE chunkifyauth;
CREATE USER 'chunkifyauth'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON chunkifyauth.* TO 'chunkifyauth'@'localhost';
FLUSH PRIVILEGES;
Code (Text):
storage:
type: "mysql"
mysql:
host: localhost
port: 3306
database: chunkifyauth
username: chunkifyauth
password: password
- player_credentials - Username, UUID, hash, timestamp
- player_sessions - Session data, timestamps
- audit_log - Security events
---
## 8️⃣ Multi-Language Support
### Available Languages
| Code | Language | Status |
| en | English | ✓ Included |
| es | Spanish | ✓ Included |
### Changing Language
config.yml
Code (Text):
# Set to "en" for English or "es" for Spanish
language: "es"
Messages are loaded from files:
- plugins/ChunkifyAuth/messages/en.yml
- plugins/ChunkifyAuth/messages/es.yml
Edit these files to customize messages.
### Supported Placeholders
- {PLAYER} - Player name
- {TIME} - Current time
- {LOCKOUT} - Lockout duration
- {ATTEMPTS} - Failed attempts
---
## 9️⃣ Version Compatibility
### Supported Versions
| Version | Status | Notes |
| 1.16.5 | ✓ Supported | Minimum version |
| 1.17.x | ✓ Supported | Full compatibility |
| 1.18.x | ✓ Supported | Full compatibility |
| 1.19.x | ✓ Supported | Full compatibility |
| 1.20.x | ✓ Supported | Full compatibility |
| 1.20.5+ | ✓ Supported | Latest versions |
### Server Types
Tested on:
- Spigot 1.16.5 - 1.20.x
- Paper 1.16.5 - 1.20.x
- Purpur (all versions)
- Folia (latest)
### Automatic Version Detection
Plugin automatically detects your server version and adapts:
- No manual configuration needed
- See version in startup logs
- Graceful fallback for unsupported features
---
## Troubleshooting
### Plugin Won't Load
Check server version
- Required: 1.16.5 or higher
- Check: /version command
- Fix: Update server if older
Check Java version
- Required: Java 8+
- Check: java -version
- Fix: Update Java installation
Check logs
- Location: logs/latest.log
- Look for: [ChunkifyAuth] error messages
- Report: Include full error message
### Database Connection Failed
Verify MySQL is running
Code (Text):
mysql -h localhost -u chunkifyauth -p
- Host, port, database name
- Username and password
- Network access (firewall)
Test connectivity
- From server machine: mysql -h <host> -u <user> -p
- From server console: /authAdmin config
- Check plugin logs for connection error
### Players Can't Login
Check password
- Passwords are case-sensitive
- Spaces not allowed
- Must be 8+ characters
Check account exists
Code (Text):
/authAdmin audit <player>
- Account locked after 5 failed attempts
- Unlock with: /authAdmin unlock <player>
- Or wait 30 minutes for automatic unlock
### Performance Issues
Check cache settings
Code (Text):
cache:
maxCacheSize: 10000
enableAutoCleanup: true
Code (Text):
/authAdmin cache # Check hit ratio
/authAdmin stats # Check authentication counts
- Increase maxConnections
- Add indexes to player_credentials table
- Check MySQL performance settings
---
## 1️⃣1️⃣ Performance Tuning
### Cache Optimization
For Small Servers (< 100 players)
Code (Text):
cache:
maxCacheSize: 1000
defaultTTLSeconds: 1800
cleanupIntervalSeconds: 300
Code (Text):
cache:
maxCacheSize: 5000
defaultTTLSeconds: 3600
cleanupIntervalSeconds: 600
Code (Text):
cache:
maxCacheSize: 50000
defaultTTLSeconds: 7200
cleanupIntervalSeconds: 1800
Connection Pool Settings
Code (Text):
mysql:
maxConnections: 5 # Small server
maxConnections: 20 # Medium server
maxConnections: 50 # Large server
connectionTimeoutMs: 5000
retryCount: 3
For Performance (Faster)
Code (Text):
passwords:
bcryptCost: 6 # Fast login (< 10ms)
Code (Text):
passwords:
bcryptCost: 12 # Secure but slower (100-200ms)
## 1️⃣2️⃣ API Reference
### For Plugin Developers
Get ChunkifyAuth Instance
Code (Text):
ChunkifyAuth plugin = (ChunkifyAuth)
Bukkit.getPluginManager().getPlugin("ChunkifyAuth");
if (plugin != null && plugin.isEnabled()) {
// Use API
}
Code (Text):
SessionManager sessions = plugin.getSessionManager();
if (sessions.hasActiveSession(player)) {
// Player is logged in
}
Code (Text):
import com.chunkify.auth.compat.VersionCompat;
String version = VersionCompat.getVersionString(); // "1.20.4"
if (VersionCompat.isSupported()) {
// Version compatible
}
Code (Text):
import com.chunkify.auth.compat.ChatCompat;
ChatCompat.sendMessage(player, "&cError: &aSystem");
ChatCompat.sendTitle(player, "&cTitle", "&aSubtitle", 10, 20, 10);
## Support
### Getting Help
- Check this documentation first
- Review troubleshooting section
- Check server logs for errors
- Verify configuration is correct
### Reporting Issues
Include:
- Minecraft version
- Server type (Spigot, Paper, etc.)
- Plugin version
- Full error from logs
- Steps to reproduce
---
ChunkifyAuth v1.2.0 - Enterprise Authentication for Minecraft
---
Last Updated: November 15, 2025
Resource Information
Author:
----------
Total Downloads:
4
First Release:
Nov 15, 2025
Last Update:
Nov 15, 2025
Category:
---------------
All-Time Rating:
0 ratings
Version
-----
Released:
--------------------
Downloads:
------
Version Rating:
----------------------
-- ratings