FiveM Discord Whitelist — Server‑Authoritative Guide

A Discord whitelist ensures only approved community members join your FiveM server. This guide gives a practical, server‑first implementation: resource files, SQL schema, a small OAuth web pattern, validation best practices, and a checklist you can follow today.

Overview

Discord whitelisting is common for role‑play and private servers. The goal is simple: map a Discord identity to a server permission and enforce it on connect. Security requires all checks run server‑side (playerConnecting/deferrals) and any web/OAuth endpoints store minimal, validated state. This guide shows a robust pattern that works with QBCore, ESX, or vanilla FiveM servers and with oxmysql or MySQL‑async.

Implementation plan (short)

1. Provide a small web endpoint where users sign in with Discord OAuth and register a one‑time code (or be added by admins).
2. Store approved Discord IDs in a database table.
3. On playerConnecting, extract the client's discord: identifier when available and check the DB; if not available, use a one‑time code flow or deny access with instructions.
4. Keep all authority and kicking in server side; log attempts and validate inputs against SQL injection using prepared statements.

Assumptions & dependencies

• Server uses MySQL with either oxmysql or mysql-async installed.
• Players can connect with a Discord identifier (recommended) or they can use a web flow to link accounts.
• No secrets are stored in the resource; OAuth client secrets live on the web server as env vars.

Files and where they belong

Create a resource folder named discord_whitelist inside your server resources. Include these files:

• fxmanifest.lua — resource manifest
• config.lua — DB table name and messages
• server.lua — authoritative connect handler
• sql/whitelist.sql — schema to create the table

fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

author 'YourName'
description 'Discord whitelist — server authoritative'
version '1.0.0'

server_scripts {
  'config.lua',
  '@oxmysql/lib/MySQL.lua', -- or remove if using mysql-async
  'server.lua'
}

config.lua

Config = {}
Config.WhitelistTable = 'discord_whitelist'
Config.DenyMessage = 'Access denied. Please link your Discord at: https://example.com/discord'

sql/whitelist.sql

CREATE TABLE IF NOT EXISTS `discord_whitelist` (
  `id` INT AUTO_INCREMENT PRIMARY KEY,
  `discord_id` VARCHAR(32) NOT NULL UNIQUE,
  `notes` VARCHAR(255) DEFAULT NULL,
  `added_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

server.lua — authoritative connect validation

AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)
  deferrals.defer()
  local src = source
  local ids = GetPlayerIdentifiers(src)
  local discordId = nil
  for _, id in ipairs(ids) do
    if string.find(id, 'discord:') then
      discordId = id:gsub('discord:', '')
      break
    end
  end

  if not discordId then
    deferrals.done(Config.DenyMessage)
    return
  end

  -- oxmysql example
  local query = 'SELECT 1 FROM '..Config.WhitelistTable..' WHERE discord_id = ? LIMIT 1'
  exports.oxmysql:execute(query, { discordId }, function(result)
    if result and #result > 0 then
      deferrals.done() -- allow
    else
      deferrals.done(Config.DenyMessage)
    end
  end)
end)

Notes: Use deferrals to provide a graceful UX while the DB is queried. Replace the oxmysql call with MySQL.Async.fetchAll if your server uses mysql-async.

Web OAuth pattern (brief)

Provide a small web app where users authenticate with Discord OAuth2 and the server writes their Discord ID to the whitelist table. The web app holds the OAuth client secret in environment variables—never commit it. An alternative is manual admin insertion via SQL.

Example notes: use passport-discord or direct OAuth code exchange. After successful auth, insert into discord_whitelist(discord_id) using prepared statements.

Security & validation

• Never accept a Discord ID from the client. Always use fiveM’s discord: identifier or a server‑verified mapping created by a secure web OAuth flow.
• Use prepared statements (oxmysql or MySQL.Async) to avoid injection.
• Log failed attempts and rate limit admin routes that modify the whitelist.
• Keep web OAuth secrets as environment variables and use HTTPS for callbacks.

QBCore / ESX considerations

playerConnecting runs outside framework specifics and remains the right place to enforce connection whitelists. If you need to sync with framework user records, do so after allow: for example, on successful allow, trigger a server event that fetches player data via QBCore.Functions.GetPlayer or ESX.GetPlayerFromId for role assignment.

Practical checklist

Testing & validation steps

1. Create a test Discord account and add it to the whitelist table.
2. Connect from a client with Discord linked and confirm allow.
3. Attempt connection from a non‑whitelisted Discord and confirm denial message.
4. Simulate DB down state and ensure deferrals handle errors and show a friendly message.

Next steps and integrations

Possible enhancements: integrate a small admin dashboard, add roles (e.g., donor, moderator) to drive group access, or add a one‑time code flow for users whose FiveM client does not expose a Discord identifier. If you want to prototype the OAuth + DB mapping quickly, use a secure workspace or script generator. Try the workspace generator at https://trystellarai.com/app to sketch the web flow and files faster. You can also iterate on deployment tasks and plan the admin UI from the same app: https://trystellarai.com/app.

For deeper reading on configuration patterns and design notes, see the project blog with additional FiveM examples: https://trystellarai.com/blog.

Keep the enforcement server‑side, avoid trusting client props, and make your whitelist auditable. With the files and checklist above you should have a secure, maintainable Discord whitelist running in a few hours.