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

• Discord Verification: Players verify by entering their Discord User ID and receiving a 4-digit code via bot DM
• Backup Password System: Set backup passwords for when Discord access is lost
• Password-Only Mode: Allow registration with just a password (no Discord required)
• Multi-Language Support: Built-in support for multiple languages (English (UK), Dutch (Belgium))
• Smart Authentication Skip: Skip login for premium accounts or matching IPs (configurable)
• Account Management: Players can unlink Discord accounts, logout, and manage passwords
• Security Options:
  • 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

# +--------------------------------------------------------------------------+
# |              ------====== 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


# +--------------------------------------------------------------------------+
# |              ------====== VERIFICATION METHODS ======------              |
# +--------------------------------------------------------------------------+
# |                                                                          |                                          |
# | Control how players verify their accounts (Discord, password, etc.)      |
# |                                                                          |
# +--------------------------------------------------------------------------+

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

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

This helps prevent brute-force attacks on accounts

max-login-attempts: 3

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

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

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

| Each group below can be set to one of these modes: |

| - disabled -> do not check this group |

| - force -> always require authentication |

| - skip-login -> skip login, but still require an account to exist |

| - no-register -> skip login and registration completely |

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

authentication-skip:

----- DEFAULTS -----

Top-level fallback used whenever a player doesn't match any group.

default-mode: "force"

Top-level fallback for password access when a player doesn't match any group.

Values: discord, password, both, disabled

password-feature-default: "both"

----- GROUPS -----

Operators can be forced, skipped, or disabled

operators: "force" operators-password-feature: "disabled"

Players whose current IP matches the IP stored on their account

known-ip: "skip-login" known-ip-password-feature: "disabled"

Specific players with per-player modes

Use name, player, or username as the key for each entry

specific-players: - name: "DebugPlayer1" mode: "disabled" password-feature: "disabled"

- name: "TestAccount"
  mode: "disabled"
  password-feature: "disabled"

Bedrock players detected through Floodgate or Geyser, when available

bedrock-players: "disabled" bedrock-players-password-feature: "disabled"

Premium Java players. On offline-mode servers, this only works when the

server or proxy still exposes a premium UUID for the session.

premium-users: "disabled" premium-users-password-feature: "disabled"

## Initial Setup

1. **Create a Discord Bot**
   - Go to Discord Developer Portal
   - 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