Intégration du Dashboard Better Auth Infrastructure

Guide d'intégration du dashboard Better Auth Infrastructure pour la gestion des utilisateurs et l'analyse d'activité

Vue d’ensemble

Le plugin dash() de Better Auth Infrastructure fournit un dashboard web pour la gestion des utilisateurs, des sessions, des organisations et l’analyse de l’activité d’authentification.

Installation et Configuration

1. Installation du package

cd apps/web
pnpm add @better-auth/infra@latest

Note : Utiliser la version @latest pour garantir la compatibilité avec Better Auth 1.7.6 et Zod v4.

2. Configuration serveur

Le plugin dash() est intégré dans src/auth/index.ts avec activation conditionnelle :

import { dash } from "@better-auth/infra";

// Prepare plugins array
const plugins: any[] = [admin()];

// Add dash plugin if API key is provided
if (env.BETTER_AUTH_API_KEY) {
  plugins.push(dash({
    apiKey: env.BETTER_AUTH_API_KEY,
    activityTracking: {
      enabled: true,
      updateInterval: 300000 // 5 minutes
    }
  }));
}

3. Configuration client

Le plugin client sentinelClient() est intégré dans src/lib/auth-client.ts :

import { sentinelClient } from "@better-auth/infra/client";

export const authClient = createAuthClient({
  plugins: [
    adminClient(),
    sentinelClient()
  ]
});

4. Configuration baseURL

Le baseURL doit inclure le base path /api/auth selon la configuration du projet Better Auth Infrastructure :

baseURL: env.BETTER_AUTH_URL || (isProd
  ? 'https://amn-dev.anderson-metsanou.workers.dev/api/auth'
  : 'http://localhost:8787/api/auth')

5. Variables d’environnement

Ajouter dans .env :

BETTER_AUTH_API_KEY=<your-better-auth-infra-api-key>

6. Migration de base de données

Le plugin ajoute le champ last_active_at à la table user pour le tracking d’activité :

# Local
npx wrangler d1 migrations apply amn-auth-db-dev --local

# Remote
npx wrangler d1 migrations apply amn-auth-db-dev --remote

Résolution du conflit de versions Zod

Problème

Better Auth 1.7.6 utilise Zod v4.6.5, mais certaines versions de @better-auth/infra et les services form-handler/submission-processor utilisaient Zod v3.25.76, créant un conflit de versions.

Solution1/3

Mettre à jour les services pour utiliser Zod v4 :

cd services/form-handler
pnpm add zod@^4.6.5

cd ../submission-processor
pnpm add zod@^4.6.5

Solution2/3

Ajouter zod et @better-auth/infra aux dépendances du monorepo dans package.json :

{
  "dependencies": {
    "better-auth": "1.7.6",
    "@better-auth/infra": "^0.4.12",
    "zod": "^4.6.5"
  }
}

Solution3/3

Reinstaller les dépendances :

cd /home/anderson/PP
rm -rf node_modules pnpm-lock.yaml
pnpm install

GitHub Actions Workflows

Les workflows de déploiement ont été mis à jour pour injecter BETTER_AUTH_API_KEY :

deploy-dev.yml

Ajout de l’injection du secret :

echo "${{ secrets.BETTER_AUTH_API_KEY }}" | npx wrangler secret put BETTER_AUTH_API_KEY --env dev --cwd apps/web

deploy-prod.yml

Ajout de l’injection du secret :

echo "${{ secrets.BETTER_AUTH_API_KEY }}" | npx wrangler secret put BETTER_AUTH_API_KEY --env prod --cwd apps/web

Configuration GitHub Secrets

Ajouter le secret BETTER_AUTH_API_KEY dans les secrets du repository GitHub avec la valeur de votre clé API Better Auth Infrastructure.

Fonctionnalités du Dashboard

Une fois activé, le dashboard Better Auth Infrastructure offre :

Gestion des utilisateurs : visualiser, rechercher, bannir et supprimer des utilisateurs
Monitoring des sessions : voir les sessions actives et les révoquer
Aperçu des organisations : gérer les organisations et leurs membres
Analytics : suivre les inscriptions, connexions et utilisateurs actifs
Logs d’audit : consulter l’historique des événements

Activation

Le plugin est activé uniquement si la variable d’environnement BETTER_AUTH_API_KEY est définie. Cela permet :

Développement sans dashboard (pas d’API key requise)
Production avec dashboard complet (API key configurée)
Build réussi même sans API key

Procédure de connexion au Dashboard

Déployer l’application sur Cloudflare via GitHub Actions (branche main)
Accéder au dashboard Better Auth Infrastructure
Entrer l’URL de l’application : https://amn-dev.anderson-metsanou.workers.dev/api/auth
Cliquer sur “Retry connection” pour vérifier la propriété
Le dashboard sera accessible une fois la connexion établie

Test local

Pour tester localement avec le dashboard :

Ajouter BETTER_AUTH_API_KEY au fichier .env local
Lancer le serveur de développement : task dev:wrangler
Accéder au dashboard via l’URL fournie par Better Auth Infrastructure
Vérifier que les endpoints Better Auth fonctionnent correctement

Déploiement

Pour le déploiement sur Cloudflare :

Ajouter BETTER_AUTH_API_KEY aux secrets GitHub Actions
Commettre et pousser les changements (workflow deploy-dev déclenché automatiquement)
Le workflow injectera le secret et déploiera
Le dashboard sera automatiquement activé en production

Dépannage

Build échoue sans API key

Le plugin est conditionnellement chargé, donc le build fonctionne même sans API key.

Erreur “zod_default.url is not a function”

Cette erreur indique un conflit de versions Zod. S’assurer que :

@better-auth/infra est en version 0.4.12 ou supérieure
zod est en version 4.6.5 dans tout le workspace
Les services form-handler et submission-processor utilisent Zod v4

Dashboard non accessible

Vérifier que BETTER_AUTH_API_KEY est correctement configurée dans les secrets Cloudflare
S’assurer que l’API key est valide et active
Vérifier que le baseURL inclut le base path /api/auth
Vérifier les logs du worker pour les erreurs de connexion

Typecheck échoue

Vérifier que l’import dans apps/web/auth.ts utilise le bon chemin :

import { dash } from "@better-auth/infra"; // Correct
// PAS import { dash } from "@better-auth/infra/plugins"; // Incorrect

Tracking d’activité non fonctionnel

Vérifier que la migration last_active_at a été appliquée
S’assurer que activityTracking.enabled est true dans la configuration