Créer un système de whitelist sur son serveur FiveM

Une whitelist FiveM limite l’accès au serveur aux joueurs préalablement autorisés. Pour une communauté RP sérieuse, elle constitue un premier filtre contre les trolls, les cheaters opportunistes et les joueurs qui ne connaissent pas le règlement.

La whitelist peut être très simple, avec une liste gérée dans txAdmin, ou s’intégrer à un processus complet de candidature sur Discord. Le bon choix dépend surtout de la taille du serveur, du framework utilisé et du niveau d’automatisation recherché.

L’objectif reste identique : identifier chaque joueur de manière fiable, vérifier son autorisation pendant la connexion et lui expliquer clairement la marche à suivre si l’accès est refusé.

Comprendre les identifiants FiveM

Lorsqu’un joueur rejoint un serveur, FiveM transmet plusieurs identifiants au serveur. Ils prennent généralement la forme d’un préfixe suivi d’une valeur unique :

• license: correspond à la licence Rockstar associée au joueur.
• license2: est un identifiant Rockstar supplémentaire, disponible dans certaines configurations.
• discord: représente l’identifiant numérique du compte Discord, lorsque celui-ci est détecté.
• steam: correspond au compte Steam, si Steam est ouvert et correctement reconnu.
• fivem: identifie le compte Cfx.re du joueur.

Une whitelist doit reposer en priorité sur un identifiant suffisamment stable. L’identifiant license: est souvent utilisé par les scripts et les frameworks, car il ne dépend pas de l’affichage d’un pseudonyme. L’identifiant discord: est particulièrement pratique lorsque les candidatures sont organisées sur Discord.

Évitez de baser une autorisation uniquement sur le nom FiveM, le pseudonyme Discord ou l’adresse IP. Ces informations peuvent changer, être copiées ou devenir indisponibles. Avant d’ajouter un joueur, vérifiez toujours que l’identifiant transmis correspond bien à celui enregistré dans votre outil d’administration ou votre base de données.

Approche 1 : activer la whitelist dans txAdmin

txAdmin propose une gestion intégrée adaptée aux serveurs qui souhaitent commencer rapidement. Depuis son interface, un administrateur peut activer le mode whitelist, consulter les demandes de connexion et approuver les joueurs autorisés. Notre guide pour démarrer avec txAdmin présente cette interface.

La procédure générale est la suivante :

1. Connectez-vous à l’interface txAdmin avec un compte disposant des permissions nécessaires.
2. Ouvrez les paramètres du serveur et recherchez la section consacrée à la whitelist.
3. Activez le mode whitelist.
4. Redémarrez le serveur si l’interface le demande.
5. Demandez au joueur de tenter une connexion afin de faire apparaître sa demande.
6. Vérifiez son identité, puis approuvez son accès dans txAdmin.

Les intitulés exacts peuvent varier selon la version de txAdmin. Vérifiez également les permissions des membres du staff : tous les modérateurs ne doivent pas nécessairement pouvoir accepter de nouveaux joueurs.

Cette méthode convient bien à une petite ou moyenne communauté. Elle ne nécessite pas de développer une ressource Lua ni de modifier directement une table MySQL. Elle devient toutefois moins pratique si plusieurs centaines de candidatures doivent être synchronisées avec Discord ou avec un site communautaire.

Approche 2 : gérer la whitelist avec ESX ou QBCore

Les serveurs ESX et QBCore utilisent généralement une base MySQL pour stocker les personnages, les permissions et les informations liées aux joueurs. Selon la distribution et les ressources installées, la whitelist peut être représentée par une colonne booléenne, une table dédiée ou un système de permissions.

Par exemple, une table peut associer un identifiant license: à un statut autorisé. À la connexion, une ressource interroge cette table et refuse le joueur si aucune entrée active n’est trouvée.

Le workflow habituel comprend plusieurs étapes :

• Récupérer la licence du candidat.
• Ajouter son identifiant dans la table prévue par la ressource.
• Activer son statut de whitelist.
• Lui demander de se reconnecter.
• Contrôler les journaux en cas de refus inattendu.

Certains scripts proposent aussi une commande administrateur en jeu, comme une commande d’ajout ou de suppression de whitelist. Le nom et la syntaxe dépendent entièrement de la ressource installée. Consultez son fichier de configuration et vérifiez que la commande exige une permission administrateur côté serveur.

Ne modifiez pas une table au hasard. ESX et QBCore ne fournissent pas tous exactement le même système de whitelist par défaut, et de nombreuses bases utilisent des ressources communautaires différentes. Avant toute modification SQL, sauvegardez la base et identifiez le script qui effectue réellement la vérification à la connexion.

Approche 3 : automatiser la whitelist avec Discord

Discord permet de transformer la whitelist en véritable parcours de candidature. Le joueur rejoint le serveur Discord, lit le règlement, remplit un formulaire puis passe éventuellement un entretien vocal. Une fois sa candidature validée, un rôle lui est attribué.

Un bot ou une ressource FiveM peut ensuite vérifier que l’identifiant discord: du joueur possède le rôle requis. Le processus peut suivre ce schéma :

1. Le candidat ouvre un ticket ou remplit un formulaire.
2. Le staff examine son expérience, sa compréhension du règlement et son projet de personnage.
3. La candidature est acceptée ou refusée.
4. Le bot attribue un rôle comme Whitelist.
5. Le joueur lie son compte Discord à son identité FiveM.
6. Le serveur vérifie le rôle lors de la connexion.

Cette approche réduit les opérations manuelles, mais ajoute une dépendance à Discord et au bot. Si Discord n’est pas détecté, un joueur pourtant autorisé peut être refusé. Prévoyez donc un message précis lui demandant d’ouvrir Discord, d’utiliser le bon compte et de relancer FiveM.

Le jeton du bot doit rester secret. Stockez-le dans une configuration serveur non publiée et limitez ses permissions au strict nécessaire.

Approche 4 : créer un script de whitelist personnalisé

Une ressource personnalisée permet de contrôler entièrement la logique. Côté serveur, l’événement playerConnecting intercepte la connexion. Les deferrals permettent de différer l’acceptation pendant que le script vérifie les identifiants ou interroge une base.

Voici un exemple Lua volontairement simplifié avec une liste locale :

local allowedLicenses = {
    ["license:1111111111111111111111111111111111111111"] = true,
    ["license:2222222222222222222222222222222222222222"] = true
}

AddEventHandler("playerConnecting", function(playerName, setKickReason, deferrals)
    local playerSource = source

    deferrals.defer()
    Wait(0)

    deferrals.update("Vérification de votre whitelist...")

    local isAllowed = false

    for _, identifier in ipairs(GetPlayerIdentifiers(playerSource)) do
        if allowedLicenses[identifier] then
            isAllowed = true
            break
        end
    end

    Wait(0)

    if isAllowed then
        deferrals.done()
    else
        deferrals.done(
            "Accès refusé. Déposez une candidature sur notre Discord."
        )
    end
end)

Placez ce code dans un script serveur déclaré dans le fxmanifest.lua, puis démarrez la ressource depuis le server.cfg. Pour un serveur en production, remplacez la liste locale par une table MySQL, un cache contrôlé ou une API interne sécurisée.

Validez toujours l’autorisation côté serveur. Une vérification effectuée uniquement dans un script client peut être contournée. Gérez aussi les erreurs de base de données : une panne temporaire ne doit pas produire un comportement ambigu ou laisser entrer tout le monde par défaut.

Gérer les candidatures et l’onboarding

Une whitelist efficace ne se limite pas à une liste d’identifiants. Elle doit s’appuyer sur un processus compréhensible pour les candidats comme pour le staff.

Définissez des critères simples : âge minimal éventuel, connaissance du règlement, qualité du projet de personnage et disponibilité pour un entretien. Utilisez une grille commune afin d’éviter les décisions incohérentes entre modérateurs.

Après validation, envoyez au joueur les instructions de connexion, les règles principales et les étapes de création de personnage. En cas de refus, affichez un message utile avec la procédure de candidature ou de recours. Un simple message « non whitelisté » génère inutilement des tickets de support.

Prévoyez également une procédure de retrait. Un bannissement, un départ du staff ou une exclusion Discord doit pouvoir révoquer rapidement l’accès FiveM.

Sécurité et bonnes pratiques

Utilisez un identifiant stable comme license: et conservez, si nécessaire, l’identifiant Discord comme correspondance secondaire. Journalisez les ajouts, les suppressions, les refus de connexion et l’administrateur responsable de chaque action. Notre guide sur les logs Discord via webhook peut aider à centraliser ce suivi.

Sauvegardez régulièrement la base ou le fichier contenant les autorisations. Ne publiez jamais une sauvegarde MySQL, un jeton Discord ou une liste complète d’identifiants dans un dépôt public.

Testez enfin plusieurs scénarios : joueur autorisé, joueur inconnu, Discord fermé, base indisponible et identifiant mal saisi. Après une mise à jour de txAdmin, du framework ou de la ressource de whitelist, vérifiez à nouveau le parcours de connexion.

Choisir la bonne solution

txAdmin est le choix le plus direct pour lancer une whitelist sans développement. ESX ou QBCore conviennent lorsque l’autorisation doit être reliée aux données du framework. Discord apporte un processus de candidature structuré, tandis qu’un script personnalisé offre le maximum de contrôle.

Les offres FiveM TalCloud démarrent à 5,49 € par mois avec txAdmin préinstallé, des vCores dédiés, une protection Anti-DDoS et un hébergement en France. Le déploiement annoncé en 60 secondes facilite la mise en ligne, tandis que la base MySQL disponible permet d’intégrer une whitelist ESX ou QBCore. Vous pouvez ainsi commencer avec txAdmin, puis automatiser progressivement les candidatures à mesure que votre communauté RP grandit.