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