DiscordAuth-Plugin

DiscordAuth Plugin

A Discord verification authentication plugin for Minecraft servers (Paper 1.21+) by theTWIXhunter. Links player accounts to Discord via DM verification codes or allows password-based authentication using the new dialogs feature.

Features

- Experimental Features: Players verify by entering their Discord User ID and receiving a 4-digit code via bot DM - Experimental Features: Set backup passwords for when Discord access is lost - Experimental Features: Allow registration with just a password (no Discord required) - Experimental Features: Built-in support for multiple languages (English UK, Dutch Belgium) - Experimental Features: Skip login for premium accounts or matching IPs (configurable) - Experimental Features: Players can unlink Discord accounts, logout, and manage passwords - Experimental Features: - Max accounts per Discord account limit - Verification timeout - Force authentication for OPs/specific permissions - Experimental Features: - Discord role sync (grant Minecraft permissions based on Discord roles) - DiscordSRV compatibility mode

Commands

- `/discordauth <reload|unlink|logout>` - Main command (aliases: `/dauth`) - `reload` - Reload the plugin configuration (admin) - `unlink [player]` - Unlink Discord account - `logout [player]` - Logout from verification session - `/password <set|change|forgot>` - Manage backup passwords (aliases: `/pw`, `/passwd`) - `/logout [player]` - Quick logout command - `/unlink [player]` - Quick unlink command

Permissions

- `discordauth.use` - Allows use of basic commands (default: true) - `discordauth.admin` - Allows use of admin commands (default: op) - `discordauth.force.login` - Force players with this permission to always authenticate

Default Configuration

```yaml

+--------------------------------------------------------------------------+

| ------====== DISCORD AUTH PLUGIN ======------ |

| --- By TheTWIXhunter --- |

+--------------------------------------------------------------------------+

| | |

| More information about this config file can be found here: |

| https://thetwixhunter.nekoweb.org/discordauth/guides/configuration.html |

| |

| !!!! ---MAKE SURE TO SET THE BOT TOKEN IN bottoken.yml--- !!!! |

| |

| The initial setup guide can be found here: |

| https://thetwixhunter.nekoweb.org/discordauth/guides/initial-setup.html |

+--------------------------------------------------------------------------+

+--------------------------------------------------------------------------+

| ------====== GENERAL SETTINGS ======------ |

+--------------------------------------------------------------------------+

Server name (shown in Discord messages)

server-name: "My Minecraft Server"

Discord server invite link (shown when DMs fail)

discord-invite: "https://discord.gg/YOUR_INVITE_CODE"

Maximum number of Minecraft accounts allowed per Discord account (0 = unlimited)

max-accounts-per-discord: 0

Language file to use (from the languages folder)

Available: en-uk.yml, nl-be.yml

language: "en-uk"

Verification timeout in seconds (0 to disable, recommended: 600 for 10 minutes)

Players will be kicked if they don't verify within this time

verification-timeout: 600

Kick players after X failed login attempts (default 3, 0 to disable)

This helps prevent brute-force attacks on accounts

max-login-attempts: 3

+--------------------------------------------------------------------------+

| ------====== VERIFICATION METHODS ======------ |

+--------------------------------------------------------------------------+

| |

| Control how players verify their accounts (Discord, password, etc.) |

| |

+--------------------------------------------------------------------------+

Discord verification (default method)

Allow registration with a Discord account

When enabled, players can register by entering their User ID or by linking their account with Discord

allow-discord-registration: true

Allow registration without Discord account

When enabled, players can register using just a password instead of linking Discord

Players enter a password during registration instead of a Discord ID

allow-password-only-registration: true

Allow players to login with password even when they have Discord linked

(for when players lose Discord access)

Players can set a password and use it to verify instead of Discord when they lost access to their account

enable-backup-password: true

+--------------------------------------------------------------------------+

| ------====== AUTHENTICATION SKIP SETTINGS ======------ |

+--------------------------------------------------------------------------+

| Authentication Skip Settings |

| Control who needs to authenticate and who can skip the login process |

| |

| - A user does not need to authenticate if any of the enabled skip rules |

| apply to them |

| - A user won't have to register if "require-registration" is false for |

| !any! of the skip rules that apply to them. |

| (They will still be required to register if all of them are False) |

| |

+--------------------------------------------------------------------------+

authentication-skip:

Skip authentication for premium (Microsoft/Mojang authenticated) accounts

Only applies when the player joins with proper Microsoft authentication

Offline mode players will still be required to login

skip-premium-accounts: enabled: true

Require premium accounts to still register initially (even if they skip login later)

require-registration: true

Skip authentication when player's IP matches their last known IP

This provides convenience for players connecting from the same location

skip-matching-ip: enabled: true

Require players to still register initially (even if they skip login later)

require-registration: true

Skip authentication for specific players (DEBUG ONLY - NOT RECOMMENDED)

Players listed here will never be asked to authenticate

Use player usernames (case-sensitive)

skip-specific-players: enabled: false

Require these players to still register initially

require-registration: false players: - "DebugPlayer1" - "TestAccount"

Force authentication overrides

Players matching these criteria MUST authenticate even if skip rules apply

force-authentication:

Force OPs to always authenticate regardless of skip rules

force-ops: true

Force players with specific permission to always authenticate

Permission: discordauth.force.login

force-permission: true ```

Initial Setup

1. Create a Discord Bot - Go to Create a Discord Bot - Create a new application - Add a bot and copy the bot token - Enable these Privileged Gateway Intents: - Server Members Intent - Message Content Intent

2. Configure the Plugin - Edit `plugins/DiscordAuth/bot-token.yml` - Replace `PUT_YOUR_BOT_TOKEN_HERE` with your bot token - Edit `plugins/DiscordAuth/config.yml` to your preferences - Set your `server-name` and `discord-invite` link

3. Invite the Bot - Use your bot's OAuth2 URL with these scopes: `bot` - Required permissions: Send Messages, Read Messages, Embed Links

For detailed setup instructions, visit: https://thetwixhunter.nekoweb.org/discordauth/guides/initial-setup.html (This site is still work in progress)

Building

Run `mvn clean package` to build the plugin. The compiled JAR will be in the `target` folder.

Installation

1. Build the plugin or download the JAR 2. Place the JAR in your server's `plugins` folder 3. Restart the server 4. Follow the Initial Setup guide above 5. Configure `plugins/DiscordAuth/bot-token.yml` and `config.yml` 6. Reload or restart the server

How It Works

First-Time Registration

1. Player joins the server 2. Plugin prompts for Discord User ID or password setup using a dialog 3. If Discord: Bot sends 4-digit code via DM → Player enters code 4. If password-only: Player sets a password 5. Account is registered and player can join

Returning Players

1. Player joins the server 2. If skip rules apply (premium/IP match), player joins immediately 3. Otherwise, player must verify with Discord code or password 4. After verification, player can join

Author

me.theTWIXhunter