Intégration Auth0 Laravel Web App

Ajoutez la connexion, la déconnexion et le profil utilisateur à une application Laravel en utilisant auth0/login (SDK Laravel Auth0).

Prérequis

Application Laravel 11+
PHP 8.2+ avec les extensions : mbstring, openssl, json
Composer installé
Application Web régulière Auth0 configurée (pas une API - doit être une Application)
Si Auth0 n'est pas encore configuré, utilisez d'abord le skill auth0-quickstart

Quand NE PAS l'utiliser

Scénario	Utilisez plutôt
API Laravel avec validation JWT Bearer	`auth0-laravel-api` (guard de token stateless)
Application web PHP pure (sans framework)	`auth0-php`
API PHP pure	`auth0-php-api`
Single Page Applications	`auth0-react`, `auth0-vue`, ou `auth0-angular`
Applications Next.js	`auth0-nextjs`
Applications web Node.js	`auth0-express` ou `auth0-fastify`
Applications web Flask	`auth0-flask`

Flux de démarrage rapide

1. Installer le SDK

composer require auth0/login

Le package auth0/login nécessite auth0/auth0-php (v8.19+) et l'installera automatiquement. Il requiert également un client HTTP PSR-18 - si vous n'en avez pas déjà, installez Guzzle :

composer require guzzlehttp/guzzle guzzlehttp/psr7

2. Publier la configuration

php artisan vendor:publish --tag=auth0

Cela crée config/auth0.php avec la configuration du guard, du middleware et des routes.

3. Configurer l'environnement

Ajoutez à votre .env :

APP_URL=http://localhost:8000
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=https://your-api-identifier
AUTH0_REDIRECT_URI=${APP_URL}/callback

AUTH0_DOMAIN est votre domaine de tenant Auth0 (sans https://). AUTH0_CLIENT_ID et AUTH0_CLIENT_SECRET proviennent des paramètres de votre Application Auth0. AUTH0_AUDIENCE doit être défini sur un identifiant d'API enregistré dans Auth0 (Tableau de bord Auth0 > Applications > APIs) - sans cela, Auth0 retourne des access tokens opaques que le SDK ne peut pas décoder, causant un crash lors de la restauration de la session. Le SDK utilise APP_KEY comme secret de cookie par défaut - aucun secret séparé n'est nécessaire.

Important : Assurez-vous que APP_URL inclut le port si vous utilisez le serveur de développement intégré (http://localhost:8000). Les installations Laravel fraîches ont par défaut http://localhost (sans port), ce qui cause des incompatibilités d'URL de callback.

4. Configurer le tableau de bord Auth0

Dans les paramètres de votre Application Auth0 :

Application Type : Regular Web Application
Allowed Callback URLs : http://localhost:8000/callback
Allowed Logout URLs : http://localhost:8000

5. Configurer les Auth Guards

Mettez à jour config/auth.php pour utiliser les guards Auth0 :

'guards' => [
    'web' => [
        'driver' => 'auth0.authenticator',
        'provider' => 'auth0-provider',
        'configuration' => 'web',
    ],
],

'providers' => [
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

La clé configuration mappe à la définition du guard dans config/auth0.php (web utilise STRATEGY_REGULAR avec l'authentification basée sur session). Nous remplaçons le guard web par défaut pour que le middleware auth intégré de Laravel et auth()->user() fonctionnent sans spécifier un nom de guard. Le SDK enregistre également automatiquement un guard auth0-session avec une configuration identique, mais remplacer web est plus simple.

6. Les routes sont enregistrées automatiquement

Le SDK enregistre automatiquement ces routes quand registerAuthenticationRoutes est true dans config/auth0.php :

GET /login - Redirige vers Auth0 Universal Login
GET /callback - Gère le callback OAuth, échange le code contre des tokens
GET /logout - Détruit la session et redirige vers la déconnexion Auth0

Aucune définition de route manuelle n'est nécessaire pour le flux d'authentification.

7. Ajouter des routes protégées

Dans routes/web.php :

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return view('home', ['user' => auth()->user()]);
});

Route::middleware('auth')->group(function () {
    Route::get('/profile', function () {
        return view('profile', ['user' => auth()->user()]);
    });
});

Le middleware standard auth fonctionne avec le guard Auth0. Les utilisateurs non authentifiés sont redirigés vers /login.

8. Créer les vues

Créez resources/views/home.blade.php :

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Home</title>
</head>
<body>
    @if($user)
        <h1>Welcome, {{ $user->name }}!</h1>
        <p><a href="/profile">Profile</a></p>
        <p><a href="/logout">Logout</a></p>
    @else
        <h1>Welcome</h1>
        <p><a href="/login">Login</a></p>
    @endif
</body>
</html>

Créez resources/views/profile.blade.php :

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Profile</title>
</head>
<body>
    <h1>{{ $user->name }}</h1>
    <p>Email: {{ $user->email }}</p>
    <img src="{{ $user->picture }}" alt="avatar" width="100" />
    <hr>
    <h2>User Claims</h2>
    <pre>{{ json_encode($user->jsonSerialize(), JSON_PRETTY_PRINT) }}</pre>
    <p><a href="/">Home</a> | <a href="/logout">Logout</a></p>
</body>
</html>

9. Tester l'authentification

php artisan serve

Visitez http://localhost:8000 et cliquez sur Login.

Important : Accédez toujours à l'application via http://localhost:8000 (pas http://127.0.0.1:8000). L'URL de callback utilise localhost, donc le cookie de session doit être défini pour localhost pour persister à travers la redirection de connexion Auth0. Utiliser 127.0.0.1 cause une erreur "Invalid state" parce que le cookie de session ne sera pas envoyé à l'URL de callback localhost.

Erreurs courantes

Erreur	Solution
Utiliser `auth0/auth0-php` directement dans Laravel	Utilisez `auth0/login` qui encapsule le SDK avec les guards, middleware et routes Laravel
Application créée comme type SPA dans le tableau de bord Auth0	Doit être Regular Web Application pour l'authentification de session côté serveur
URL de callback manquante dans le tableau de bord Auth0	Ajoutez `http://localhost:8000/callback` à Allowed Callback URLs
URL de déconnexion manquante dans le tableau de bord Auth0	Ajoutez `http://localhost:8000` à Allowed Logout URLs
Configuration non publiée	Exécutez `php artisan vendor:publish --tag=auth0` avant de configurer
Mauvais nom de driver du guard	Le driver est `auth0.authenticator` (pas `auth0` ou `auth0.guard`)
Oublier de définir `APP_KEY`	Exécutez `php artisan key:generate` - le SDK l'utilise comme secret de cookie
Appeler `Auth0::getCredentials()` directement	Utilisez `auth()->user()` de Laravel - le SDK s'intègre via les guards
Définir manuellement les routes `/login`, `/callback`, `/logout`	Les routes sont enregistrées automatiquement par le service provider
Définir `AUTH0_DOMAIN` avec le préfixe `https://`	Utilisez le domaine nu : `tenant.us.auth0.com` pas `https://tenant.us.auth0.com`
Utiliser `$request->user()` sans middleware	Uniquement disponible dans les routes avec le middleware `auth` appliqué
Variable d'env `AUTH0_AUDIENCE` manquante	Sans audience, Auth0 retourne des tokens opaques que le SDK ne peut pas traiter - cause le crash "JWT string must contain two dots"
Visiter `http://127.0.0.1:8000` au lieu de `http://localhost:8000`	Les cookies de session définis pour `127.0.0.1` ne seront pas envoyés au callback `localhost` - cause l'erreur "Invalid state"
Utiliser `$user->getName()` ou `$user->getEmail()`	`StatefulUser` utilise la magie `__get` - utilisez `$user->name`, `$user->email`, `$user->picture`

Méthodes clés du SDK

Méthode	Utilisation	Objectif
`auth()->user()`	Dans les routes/contrôleurs	Retourne l'utilisateur authentifié `StatefulUser` ou `null`
`auth()->check()`	Dans les routes/contrôleurs/vues	Retourne `true` si l'utilisateur est authentifié
`auth()->guard('web')`	Lors de l'utilisation de plusieurs guards	Obtient une instance Auth0 guard spécifique
`$user->name`	Sur l'objet utilisateur	Nom d'affichage de l'utilisateur (via la magie `__get`)
`$user->email`	Sur l'objet utilisateur	Email de l'utilisateur (via la magie `__get`)
`$user->picture`	Sur l'objet utilisateur	URL de l'avatar de l'utilisateur (via la magie `__get`)
`$user->getAuthIdentifier()`	Sur l'objet utilisateur	Retourne la réclamation Auth0 `sub`
`$user->getAttribute('claim')`	Sur l'objet utilisateur	Retourne toute valeur de réclamation explicitement
`$user->jsonSerialize()`	Sur l'objet utilisateur	Retourne toutes les réclamations utilisateur sous forme de tableau

Objet utilisateur

L'utilisateur authentifié est une instance StatefulUser implémentant le contrat Authenticatable de Laravel. Il utilise la magie __get pour accéder par style propriété aux réclamations :

$user = auth()->user();

$user->name;                   // nom d'affichage (via __get)
$user->email;                  // adresse email (via __get)
$user->picture;                // URL d'avatar (via __get)
$user->email_verified;         // toute réclamation via accès propriété
$user->getAuthIdentifier();   // Auth0 'sub' (ex. 'auth0|abc123')
$user->getAttribute('sub');    // accès explicite aux réclamations
$user->jsonSerialize();        // toutes les réclamations sous forme de tableau

Accédez à toute réclamation du ID token sous forme de propriété : $user->nickname, $user->updated_at, $user->sub, etc. Pour un accès explicite, utilisez $user->getAttribute('claim_name').

Skills associés

auth0-laravel-api - Protéger les routes API Laravel avec la validation du token Bearer JWT
auth0-php - Applications web PHP pure sans framework
auth0-quickstart - Configuration initiale Auth0
auth0-mfa - Ajouter l'authentification multifacteur
auth0-cli - Gérer les ressources Auth0 depuis le terminal

Référence rapide

Configuration du guard (config/auth.php) :

'guards' => [
    'web' => [
        'driver' => 'auth0.authenticator',
        'provider' => 'auth0-provider',
        'configuration' => 'web',
    ],
],
'providers' => [
    'auth0-provider' => [
        'driver' => 'auth0.provider',
        'repository' => 'auth0.repository',
    ],
],

Protection des routes :

Route::middleware('auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Vérifier l'authentification en Blade :

@auth
    <p>Hello, {{ auth()->user()->name }}</p>
@else
    <a href="/login">Login</a>
@endauth

Variables d'environnement :

APP_URL - URL de l'application avec port (ex. http://localhost:8000)
AUTH0_DOMAIN - Domaine du tenant Auth0 (ex. tenant.us.auth0.com)
AUTH0_CLIENT_ID - ID client de l'application
AUTH0_CLIENT_SECRET - Secret client de l'application
AUTH0_AUDIENCE - Identifiant d'API (requis pour les access tokens JWT)
AUTH0_REDIRECT_URI - URL de callback (par défaut ${APP_URL}/callback)
APP_KEY - Clé de l'application Laravel, utilisée comme secret de chiffrement du cookie

Documentation détaillée

Guide de configuration - Scripts de configuration automatisée, configuration de l'environnement, utilisation de l'Auth0 CLI
Guide d'intégration - Vérification des scopes, appel d'API, événements, modèles utilisateur personnalisés, gestion de session
Référence API - API de guard complet, options de configuration, méthodes du modèle utilisateur

auth0-laravel