PkLogin

PkLogin

A secure, modern and feature-rich authentication plugin for Spigot, Paper, Folia and Velocity.

🤖 AI Usage Disclosure

AI tools were used to assist with code development, translations, and this README/documentation.

✨ Features

🔐 Authentication

• Paper, Folia & Velocity support.
• Verified account auto-login — Authenticated Minecraft accounts can join without creating a local password when ownership is successfully verified.
• Login sessions — Skip passwords on trusted reconnects for a configurable period.
• Brute-force protection — Limit failed login attempts.
• IP account limits — Control how many accounts can be registered from one IP.
• Login timeout — Automatically disconnect unauthenticated players.
• Limbo system — Block movement, commands and chat until authentication.
• Safe teleportation — Send players to a safe location before login and restore their previous location afterward.
• Username conflict handling — Prevent conflicts between different account and UUID modes.

🛰️ Velocity Integration

• Zero manual proxy configuration — PkLogin automatically detects the network's forwarding configuration.
• Authenticated proxy messages — Uses HMAC signing derived from Velocity's modern forwarding secret.
• Backend verification — The proxy can verify that authentication servers are running PkLogin and using the same signing key.
• Requires Velocity modern forwarding for secure verified-account auto-login.

🔑 Password Security

Supports multiple hashing algorithms:

Automatic hash migration: Change the configured algorithm at any time. Existing supported password hashes are detected automatically and re-hashed after the player's next successful login.

🔒 Two-Factor Authentication

• Discord 2FA with DM-based verification codes.
• Single-use 6-digit codes.
• Codes expire after 5 minutes and have limited attempts.
• Additional 2FA methods are planned for future releases.

🗄️ Database Support

• SQLite — Default, zero configuration
• H2
• MySQL
• MariaDB
• PostgreSQL

🔄 Migration

AuthMe → PkLogin

/pklogin authme-import

Imports existing accounts while preserving supported passwords, IP information and registration dates.

Database Migration

/pklogin migrate <engine>

Move accounts between supported database engines without deleting the original data.

Existing accounts are skipped, making migrations safe to re-run.

🌍 Internationalization

20+ built-in languages, including:

English, Spanish, Portuguese, French, German, Russian, Chinese, Polish, Italian, Turkish, Vietnamese and more.

📡 UUID Modes

Choose how account UUIDs are handled:

• REAL — Uses the authenticated Minecraft account UUID.
• RANDOM — Generates a random UUID.
• OFFLINE — Uses Minecraft's standard offline UUID generation.

🛡️ Security

PkLogin is designed around secure authentication by default.

Verified Account Auto-Login

PkLogin can verify eligible Minecraft accounts and allow them to join without creating a separate PkLogin password.

For unknown usernames, PkLogin can query Mojang's account services and, when applicable, perform the standard Minecraft online authentication handshake.

Successful authentication provides cryptographic verification of the connecting account.

If external account services are temporarily unavailable, PkLogin can use the server's configured local authentication behavior instead of relying on an unverified online authentication result.

On standalone Paper servers, verified-account auto-login requires PacketEvents or ProtocolLib. Velocity handles the required proxy-side authentication flow automatically.

Login Sessions

Sessions allow authenticated players to reconnect without entering their password again.

Security:
  session:
    enable: true
    timeout: 5

Sessions are:

• Time-limited
• Bound to the player's IP address
• Single-use
• Stored only in memory

They are automatically invalidated when passwords or 2FA settings change, accounts are deleted, or PkLogin is reloaded.

Security note: IP addresses are not unique identities. Keep session timeouts short, especially on shared networks.

🛠️ Commands

Player Commands

Admin Commands

Every command has its own permission.

⚙️ Configuration

PkLogin is highly configurable while remaining simple to set up.

Security:
  time-to-login: 45
  hash-algorithm: BCRYPT

  password:
    small: 5
    large: 15

  session:
    enable: true
    timeout: 5

autologin:
  premium:
    enable: true
    cache-minutes: 60

  bedrock:
    enable: true
    skip-register: true

passwords:
  bruteforce:
    max-login-tries: 3

security:
  ip-limit:
    enable: true
    limit: 3

teleport:
  safe-location: true
  last-location: true

limbo:
  blindness-effect: false

username-appender:
  enabled: false

🔌 Proxy Setup

PkLogin requires no additional proxy secret or proxy-mode option.

When running behind Velocity, PkLogin automatically reads the forwarding configuration already used by the network and derives a separate signing key from Velocity's modern forwarding secret.

This provides:

• Secure proxy → backend authentication
• Protection against forged authentication messages
• Automatic backend compatibility checks
• No duplicated secrets across multiple configuration files

For production networks, Velocity modern forwarding + firewalling backend ports is strongly recommended.

🔒 Discord 2FA

Configuration:

# plugins/PkLogin/2fa/discord.yml

enable: false

authentication:
  token: "YOUR_BOT_TOKEN_HERE"

Link an account with:

/2fa discord

Then send the generated verification code to the configured Discord bot.

🔄 Migrating from AuthMe

1. Place your authme.db in:

plugins/AuthMe/authme.db

1. Run:

/pklogin authme-import

PkLogin imports compatible accounts asynchronously and preserves their supported existing password hashes.

When possible, hashes are automatically migrated to the configured hashing algorithm after a successful login.

📄 License

MIT License — © 2020–2026 PkLogin Contributors