# 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: | Algorithm | Use | | --------------------- | --------------------------- | | **BCrypt** | Recommended default | | **Argon2id** | Strong password hashing | | **PBKDF2** | 600,000 iterations | | **SHA-512 / SHA-256** | Salted compatibility modes | | **AuthMe SHA256** | Read-only migration support | **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 ```text /pklogin authme-import ``` Imports existing accounts while preserving supported passwords, IP information and registration dates. #### Database Migration ```text /pklogin migrate ``` 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. ```yaml 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 | Command | Description | | ----------------------------- | -------------------------------------- | | `/login ` | Log in | | `/register ` | Register a local account | | `/changepassword ` | Change password | | `/unregister ` | Delete local credentials | | `/premium confirm` | Enable verified Minecraft account mode | | `/offline` | Switch to local account mode | | `/2fa discord` | Link Discord 2FA | | `/2fa verify2fa

`       | Verify a 2FA code                      |

### Admin Commands

Every command has its own permission.

| Command                             | Description                      |
| ----------------------------------- | -------------------------------- |
| `/pklogin help`                     | Show admin commands              |
| `/pklogin reload`                   | Reload configuration             |
| `/pklogin authme-import`            | Import AuthMe accounts           |
| `/pklogin migrate `         | Migrate database engines         |
| `/pklogin forcelogin `        | Force-login a player             |
| `/pklogin unregister `        | Remove a player's local password |
| `/pklogin delete `            | Permanently delete an account    |
| `/pklogin changepass  ` | Change a player's password       |
| `/pklogin verify `            | View account information         |
| `/pklogin dupeip `         | Find accounts sharing an IP      |
| `/pklogin setspawn`                 | Set the pre-login spawn          |
| `/pklogin update`                   | Download the latest version      |

---

## ⚙️ Configuration

PkLogin is highly configurable while remaining simple to set up.

```yaml
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:

```yaml
# plugins/PkLogin/2fa/discord.yml

enable: false

authentication:
  token: "YOUR_BOT_TOKEN_HERE"
```

Link an account with:

```text
/2fa discord
```

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

---

## 🔄 Migrating from AuthMe

1. Place your `authme.db` in:

```text
plugins/AuthMe/authme.db
```

2. Run:

```text
/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](LICENSE) — © 2020–2026 PkLogin Contributors

Pumpkings