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.)      |
# |                                                                          |
# +--------------------------------------------------------------------------+

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