Configurer la connexion OAuth

Créer et vérifier un compte réel

L'authentification signifie prouver qui utilise l'application. Démarrez Postgres et exécutez d'abord les migrations à l'aide du guide de base de données, puis laissez le serveur Web en cours d'exécution. Ouvrez http://localhost:3000/auth,, choisissez inscription par e-mail/mot de passe, entrez votre nom, votre e-mail et votre mot de passe, puis soumettez. Conservez EMAIL_PROVIDER=local pour ce premier test.

Lorsqu'un flux demande un code de courrier électronique, ouvrez http://localhost:3000/mail-preview dans un autre onglet du navigateur, recherchez le message le plus récent pour cette adresse et recopiez son code dans le formulaire de connexion. Demandez un nouveau code s’il expire. Ces messages restent dans la boîte d'envoi locale ; vérifier à plusieurs reprises une boîte de réception externe ne les trouvera pas. Déconnectez-vous, puis reconnectez-vous pour confirmer que le compte sauvegardé par la base de données fonctionne.

Si l'inscription signale une connexion à la base de données ou une erreur de table manquante, terminez la configuration de la base de données au lieu d'activer la connexion sociale. Les boutons Google, GitHub, Apple, X et Microsoft nécessitent leur propre application fournisseur et leurs propres paramètres de rappel ; activez-en un uniquement une fois son guide du fournisseur terminé. Better Auth est le moteur par défaut livré et ne nécessite pas de compte d'authentification payant pour la connexion par courrier électronique local.

• Démarrez Postgres avant de créer un compte
• Utiliser et dépanner les codes de connexion par courrier électronique
• Configurer la connexion Google
• Ajouter la connexion Google
• Ajouter la connexion GitHub
• Ajouter la connexion Apple

Choisir les méthodes de connexion activées

La base comprend la connexion par e-mail et mot de passe, les codes OTP et l’authentification sociale configurable. Better Auth gère l’identité et les sessions, tandis que l’application compose la configuration des fournisseurs et l’envoi transactionnel des codes OTP.

Activez uniquement les fournisseurs sociaux que vous avez configurés. Les secrets client des fournisseurs et le secret d’authentification restent côté serveur.

Relier l’identité à un espace de travail

Les gestionnaires authentifiés résolvent l’état de la session avant d’accéder aux données de l’espace de travail. La création d’un espace de travail doit rester idempotente afin que la répétition d’un hook de cycle de vie ne crée pas de doublons dans les enregistrements de propriété.

Vérifier le comportement des sessions

Testez la connexion, les codes OTP invalides ou expirés, leur utilisation unique, la déconnexion et le refus des accès anonymes. Les tests avec adaptateur mémoire couvrent la sémantique des gestionnaires ; la persistance en base de données en production et les vrais rappels des fournisseurs nécessitent une validation distincte.

Configuration et paramètres

1. Définissez AUTH_SECRET sur au moins 32 caractères aléatoires — openssl rand -hex 32 fait l'affaire.

2. Dans la console développeur de chaque fournisseur, créez une app OAuth et enregistrez l'URL de callback : {APP_URL}/api/auth/callback/<provider> sous Better Auth (l'AUTH_PROVIDER par défaut). Utilisez des apps séparées pour le local et la production là où le fournisseur n'accepte qu'un seul callback — docs/github-auth-setup.md détaille le flux GitHub de bout en bout.

3. Basculez le drapeau du fournisseur et définissez sa paire client — AUTH_GOOGLE_ENABLED plus GOOGLE_CLIENT_ID et GOOGLE_CLIENT_SECRET, et le trio correspondant pour Apple, GitHub, Microsoft ou Twitter. Activer un drapeau sans ses identifiants fait échouer le démarrage en nommant la variable manquante.

4. Microsoft est le seul callback qui diffère selon le moteur : /api/auth/callback/microsoft sous Better Auth, /api/auth/callback/microsoft-entra-id sous Auth.js.

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

Processus d’implémentation

Les comptes externes de workspace sont une surface différente : les paires CONNECTED_X_*, CONNECTED_GOOGLE_* et CONNECTED_MICROSOFT_* alimentent Paramètres → Connexions, et leurs callbacks vivent sous {APP_URL}/api/accounts/{x|google|microsoft}/callback. Un client id vide laisse le flux de connexion de ce fournisseur désactivé — n'y réutilisez pas les identifiants de l'app de connexion.

Les secrets client des fournisseurs restent réservés au serveur, exactement comme AUTH_SECRET — jamais dans des variables NEXT_PUBLIC_ ou EXPO_PUBLIC_.

Connexion fonctionnelle ? Continuez vers Configurer l'IA.

Vérification et dépannage

Testez une première connexion, une session de retour, un écran de consentement annulé et un fournisseur désactivé. Un callback mal enregistré est l'échec habituel — l'URL enregistrée doit correspondre exactement à APP_URL et à l'id de callback du moteur, et l'app a besoin d'un redémarrage après un changement d'env.