Ajouter la connexion à votre application Laravel

Ce guide explique comment intégrer Auth0 à une application Laravel nouvelle ou existante à l’aide de l’Auth0 Laravel SDK.

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant IA de programmation comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide d’Agent Skills.

Installer :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Laravel app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, installera auth0/login, configurera les variables d’environnement et ajoutera les routes d’authentification. Documentation complète d’Agent Skills →

Prérequis : Avant de commencer, assurez-vous d’avoir installé les éléments suivants :

• PHP 8.2 ou une version plus récente
• Composer 2.x
• Laravel 11, 12 ou 13

Vérifiez l’installation : php --version && composer --version

​

Pour commencer

Ce Quickstart montre comment ajouter l’authentification Auth0 à une application Laravel. Vous y configurerez une connexion sécurisée, le logout, des routes protégées et l’accès au profil utilisateur à l’aide du Auth0 Laravel SDK.

1. Créer un nouveau projet Laravel

   Si vous avez déjà une application Laravel, passez à l’étape 2.

   Créez un nouveau projet Laravel :

   composer create-project laravel/laravel auth0-laravel-app
   

   Ouvrez le dossier du projet :

   cd auth0-laravel-app
   
2. Installer l’Auth0 Laravel SDK

   Exécutez la commande suivante dans le répertoire de votre projet afin d’installer le Auth0 Laravel SDK :

   composer require auth0/login:^7 --update-with-all-dependencies
   

   Ensuite, publiez le fichier de configuration du SDK :

   php artisan vendor:publish --tag auth0
   
3. Configurer les identifiants Auth0

   Vous devez créer une application Auth0 et ajouter vos identifiants au projet. Choisissez l’une des méthodes suivantes :

   Configuration rapide (recommandée)

   Créez une Auth0 App et copiez les identifiants .env préremplis avec les bonnes valeurs de configuration.

   Ajoutez ces valeurs au fichier .env de votre projet :

   CLI

   Exécutez la commande suivante dans le répertoire racine de votre projet afin de créer une application Auth0 et de générer un fichier .env :

   Mac

   # Installez Auth0 CLI (s’il n’est pas déjà installé)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Configurez l’application Auth0 et générez le fichier .env
   auth0 qs setup --app --type regular --framework laravel --build-tool composer --name "My Laravel App" --port 8000
   

   Cette commande va :

   1. Vérifier si vous êtes authentifié (et vous inviter à vous connecter au besoin)
   2. Créer une Regular Web Application Auth0 configurée pour http://localhost:8000
   3. Générer un fichier .env contenant vos identifiants Auth0

   Dashboard

   1. Accédez au Auth0 Dashboard → Applications > Applications
   2. Cliquez sur Create Application, entrez un nom, sélectionnez Regular Web Application, puis cliquez sur Create
   3. Accédez à l’onglet Settings et copiez le Domain, le Client ID et le Client Secret

   Configurez les URL suivantes dans l’onglet Settings de votre application :

   Champ	Valeur
   Allowed Callback URLs	http://localhost:8000/callback
   Allowed Logout URLs	http://localhost:8000

   Cliquez sur Save Changes.

   Ajoutez ensuite vos identifiants au fichier .env de votre projet :

   .env

   AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
   AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID
   AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET
   

   Ne validez jamais votre AUTH0_CLIENT_SECRET dans le contrôle de version. Conservez-le dans .env et assurez-vous que .env figure dans votre .gitignore.

4. Ajouter des routes d’authentification

   Le SDK Auth0 enregistre automatiquement les routes suivantes pour votre application — aucune configuration supplémentaire des routes n’est nécessaire :

   Route	Description
   /login	Lance le flux de connexion Auth0
   /logout	Déconnecte l’utilisateur et le redirige vers Auth0
   /callback	Traite le retour d’authentification Auth0

   Si votre application utilise Laravel Breeze, Fortify ou Jetstream, les routes /login, /logout et /callback du SDK peuvent entrer en conflit avec les routes enregistrées par ces packages. Consultez le README du SDK pour savoir comment enregistrer manuellement les routes.

   Mettez à jour routes/web.php pour ajouter votre route d’accueil :

   routes/web.php

   <?php
   
   use Illuminate\Support\Facades\Route;
   
   Route::get('/', function () {
       if (! auth()->check()) {
           return response('You are not logged in. <a href="/login">Log in</a>');
       }
   
       $user = auth()->user();
       $name = $user->name ?? 'User';
       $email = $user->email ?? '';
   
       return response("Hello {$name}! Your email address is {$email}.");
   });
   
5. Protégez les routes avec un middleware

   Utilisez le middleware auth de Laravel pour exiger l’authentification sur toute route. Vous pouvez aussi appliquer des permissions précises à l’aide du middleware can :

   routes/web.php

   <?php
   
   use Illuminate\Support\Facades\Route;
   
   // Nécessite un utilisateur authentifié
   Route::get('/private', function () {
       return response('Welcome! You are logged in.');
   })->middleware('auth');
   
   // Nécessite l'authentification ET la permission 'read:messages'
   Route::get('/scope', function () {
       return response('You have the read:messages permission.');
   })->middleware('auth')->can('read:messages');
   

   Les autorisations sont définies dans les paramètres de votre API Auth0 et attribuées aux utilisateurs par l’intermédiaire de rôles. Consultez le contrôle d’accès basé sur les rôles pour plus de détails.

6. Lancez votre application

   php artisan serve
   

   Votre application est accessible à http://localhost:8000. Si le port 8000 est déjà utilisé, exécutez php artisan serve --port=8001 et mettez à jour les Allowed Callback URLs et Allowed Logout URLs de votre application Auth0 afin d’utiliser le nouveau port.

Vérification

Ouvrez http://localhost:8000 dans votre navigateur. Essayez ces routes pour vérifier votre intégration :

• http://localhost:8000/login — déclenche le flux de connexion Auth0
• http://localhost:8000/private — redirige vers la page de connexion si l’utilisateur n’est pas authentifié ; affiche un message de bienvenue lorsqu’il est connecté
• http://localhost:8000/logout — déconnecte l’utilisateur et le ramène à la page d’accueil

---

​

Résolution des problèmes

Erreur de non-correspondance d’URL de rappel

Cause : L’URL de rappel envoyée à Auth0 ne correspond à aucune URL dans la liste Allowed Callback URLs de votre application.

Correctif :

1. Accédez à Auth0 Dashboard → Applications > Applications → votre application → Settings
2. Ajoutez http://localhost:8000/callback à Allowed Callback URLs
3. Cliquez sur Save Changes

Assurez-vous qu’il n’y a pas de barre oblique à la fin et que le port correspond à celui de votre serveur en cours d’exécution.

Erreur invalid state / CSRF après la connexion

Cause : Mauvaise configuration de la session ou du cookie — la session Laravel ne conserve pas le paramètre state entre la redirection de connexion et l’URL de rappel.

Correctif :

1. Assurez-vous que SESSION_DRIVER dans .env est défini à file, database ou redis (et non array)
2. Videz la configuration et le cache :

php artisan config:clear && php artisan cache:clear

3. Redémarrez votre serveur de développement

AUTH0_DOMAIN non défini ou identifiants non chargés

Cause : Le SDK ne trouve pas vos identifiants Auth0.

Correctif : Assurez-vous que l’un des éléments suivants existe à la racine de votre projet :

• Un fichier .env avec AUTH0_DOMAIN, AUTH0_CLIENT_ID et AUTH0_CLIENT_SECRET
• Un fichier .auth0.app.json généré par l’Auth0 CLI

Après avoir mis à jour .env, videz le cache de configuration :

php artisan config:clear

Erreur 404 sur /login, /logout ou /callback

Cause : Les routes du SDK ne sont pas enregistrées, généralement parce que le fournisseur de services ne s’est pas chargé.

Correctif :

1. Assurez-vous d’avoir exécuté php artisan vendor:publish --tag auth0
2. Vérifiez que la découverte automatique des packages est activée (vérifiez composer.json pour "dont-discover": [])
3. Exécutez php artisan route:list | grep auth0 pour confirmer que les routes sont enregistrées
4. Si des routes sont manquantes, enregistrez manuellement le fournisseur de services. Dans Laravel 11+, ajoutez-le à bootstrap/providers.php :

bootstrap/providers.php

return [
    App\Providers\AppServiceProvider::class,
    Auth0\Laravel\Auth0ServiceProvider::class,
];

---

​

Utilisation avancée

Management API — mettre à jour les métadonnées utilisateur

Vous pouvez mettre à jour les informations utilisateur à l’aide de l’Auth0 Management API. Tous les points de terminaison de la Management API sont accessibles via la méthode Auth0::management() du SDK.

Avant d’effectuer des appels à la Management API, autorisez votre application à accéder à la Management API :

1. Accédez au Auth0 Dashboard → Applications > APIs → Auth0 Management API
2. Sélectionnez l’onglet Machine to Machine Applications
3. Autorisez votre application Laravel et accordez les scopes read:users et update:users

routes/web.php

<?php

use Auth0\Laravel\Facade\Auth0;
use Illuminate\Support\Facades\Route;

Route::get('/colors', function () {
    $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange'];

    $users = Auth0::management()->users();

    // Met à jour les métadonnées de l’utilisateur authentifié avec une couleur préférée aléatoire
    $users->update(
        id: auth()->id(),
        body: [
            'user_metadata' => [
                'color' => $colors[random_int(0, count($colors) - 1)],
            ],
        ]
    );

    // Récupère et affiche les métadonnées mises à jour
    $metadata = Auth0::json($users->get(auth()->id()));
    $color = $metadata['user_metadata']['color'] ?? 'unknown';
    $name = auth()->user()->name;

    return response("Hello {$name}! Your favorite color is {$color}.");
})->middleware('auth');

La référence complète de toutes les méthodes de la Management API est offerte dans la documentation du SDK.

Modèles utilisateur personnalisés et repositories

Le SDK prend en charge les modèles utilisateur personnalisés et les repositories, ce qui vous permet de stocker et de récupérer des utilisateurs dans votre propre base de données tout en conservant Auth0 comme fournisseur d’identité.

Consultez User Repositories and Models pour obtenir le guide complet de mise en œuvre.

Écoute des événements du SDK

Le SDK déclenche des événements à des moments clés du cycle de vie de l’authentification — à la connexion, à la déconnexion, à l’actualisation du token, et plus encore — ce qui vous permet de personnaliser entièrement son comportement sans modifier le code de base du SDK.

Consultez Hooking Events pour obtenir la liste complète des événements et des exemples de mise en œuvre.

Role-Based Access Control (RBAC)

Utilisez Auth0 RBAC pour attribuer des permissions aux utilisateurs par l’intermédiaire de rôles, puis les appliquer dans Laravel à l’aide du middleware can :

routes/web.php

<?php

use Illuminate\Support\Facades\Route;

Route::get('/admin', function () {
    return response('Admin area.');
})->middleware('auth')->can('admin:dashboard');

Pour configurer RBAC :

1. Accédez au Auth0 Dashboard → Applications > APIs → votre API → Permissions
2. Ajoutez les permissions dont votre application a besoin (p. ex. admin:dashboard, read:messages)
3. Accédez à User Management > Roles, créez un rôle et attribuez-lui des permissions
4. Attribuez le rôle aux utilisateurs à partir de leur page de profil

Consultez Role-Based Access Control pour le guide complet.

---

​

Prochaines étapes

Maintenant que l’authentification fonctionne dans votre application Laravel, explorez davantage les fonctionnalités d’Auth0 :

• Auth0 Dashboard — Configurez et gérez votre tenant Auth0 et vos applications
• laravel-auth0 SDK — Documentation complète du SDK et intégrations avancées
• Role-Based Access Control — Attribuez des permissions aux utilisateurs à l’aide de rôles
• Auth0 Marketplace — Découvrez des intégrations pour étendre les fonctionnalités d’Auth0