Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xreatlabs.space/llms.txt

Use this file to discover all available pages before exploring further.

​
Paper/Purpur Installation

This guide walks you through installing NexAuth directly on your Paper or Purpur server for single-server authentication.

​
Prerequisites

  • Java 21 or newer
  • Paper 1.20+ or Purpur
  • Administrative access to server files
  • Server must run in offline mode

​
Installation Steps

1
Download or Build NexAuth
Choose one of these methods:Option A: Download from ReleasesDownload the latest NexAuth.jar from the GitHub Releases
A single NexAuth.jar works on both Paper/Purpur servers and Velocity proxies - no separate files needed.
Option B: Build from Source
# Clone the repository
git clone https://github.com/xreatlabs/NexAuth.git
cd NexAuth

# Build the plugin
./gradlew :Plugin:shadowJar
The JAR will be available at Plugin/build/libs/NexAuth.jar
2
Configure Server Properties
Before installing, ensure your server runs in offline mode:Edit server.properties:
online-mode=false
motd=NexAuth Server
server-port=25565
Setting online-mode=false is required for NexAuth to function properly.
3
Install on Paper/Purpur
  1. Stop your Paper/Purpur server
  2. Navigate to the plugins/ directory
  3. Copy NexAuth.jar into the plugins/ directory
  4. Start your Paper/Purpur server
4
Initial Configuration Generation
After first startup:
  1. The plugin will generate a configuration file at plugins/NexAuth/config.conf
  2. The server will automatically shut down after generating the config
  3. This is normal behavior - we’ll configure it in the next step
This automatic shutdown is expected behavior. The plugin needs to generate the default configuration before running.
5
Edit Configuration
Edit plugins/NexAuth/config.conf with your preferred settings:
# Example basic configuration for Paper mode
database {
    type=nexauth-sqlite
    properties {
        sqlite {
            path="user-data.db"
        }
    }
}

# Premium authentication
auto-register=false
profile-conflict-resolution-strategy=BLOCK

# Security settings
default-crypto-provider=BCrypt-2A
hide-player-inventory=true
6
Restart and Verify
  1. Start your Paper/Purpur server again
  2. Test authentication with both:
    • Premium accounts (auto-login)
    • Offline accounts (registration required)
  3. Check the logs for any errors

​
Configuration Reference

​
Key Settings for Paper Mode

# Database configuration
database {
    type=nexauth-sqlite
    properties {
        sqlite {
            path="user-data.db"
        }
    }
}

# Premium authentication
auto-register=false
profile-conflict-resolution-strategy=BLOCK
default-crypto-provider=BCrypt-2A

# Security settings
max-login-attempts=-1
milliseconds-to-refresh-login-attempts=10000
hide-player-inventory=true

# Session management
session-timeout=604800

# UI settings
use-titles=true
use-action-bar=false

# Server configuration (worlds on Paper)
limbo=["limbo_world"]
lobby {
    root=["world", "lobby"]
}

​
Paper-Specific Features

​
Inventory Hiding

NexAuth can hide player inventories during authentication: 
hide-player-inventory=true

​
Protocol Support

For Bedrock players via Geyser/Floodgate: 
new-uuid-creator=CRACKED
profile-conflict-resolution-strategy=BLOCK

​
Troubleshooting

​
Common Issues

​
Plugin generates config then shuts down

This is normal behavior. Edit the config file and restart the server.

​
Players getting kicked immediately on join

  • Ensure online-mode=false in server.properties
  • Check that no other authentication plugins are installed
  • Verify the configuration is correct

​
Inventory hiding not working

  • Ensure hide-player-inventory=true in config
  • Check for conflicts with other inventory plugins
  • Verify you’re using Paper/Purpur (not Spigot)

​
Performance issues

  • Consider using MySQL instead of SQLite for larger servers
  • Adjust register-delay if experiencing lag
  • Check server resources

​
Log Locations

  • Paper/Purpur: /path/to/server/logs/
  • NexAuth Logs: Included in server logs

​
Performance Tips

​
For Large Servers

# Use MySQL instead of SQLite
database {
    type=nexauth-mysql
    properties {
        mysql {
            host="localhost"
            port=3306
            database="nexauth"
            user="nexauth"
            password="yourpassword"
        }
    }
    transient-retries=3
    transient-retry-delay-ms=250
}

​
For Bedrock Players

# Geyser/Floodgate support
new-uuid-creator=CRACKED
profile-conflict-resolution-strategy=BLOCK

​
Comparison: Paper vs Velocity Mode

FeaturePaper ModeVelocity Mode
InstallationDirect on serverOn proxy only
Backend SecurityServer exposed to internetBackend servers protected
Multi-ServerSingle server onlyMultiple servers supported
Setup ComplexitySimpleRequires proxy configuration
PerformanceDirectSlight overhead from proxy

​
Next Steps