PHP

Par Evan Sims

Ce guide explique comment intégrer Auth0 à une application PHP à l’aide de l’Auth0 PHP SDK. Nous vous recommandons de vous connecter pour suivre ce Quickstart avec des exemples configurés pour votre compte.

Vous débutez avec Auth? Découvrez comment fonctionne Auth0, comment il s’intègre aux Regular Web Applications et quel protocole il utilise.

Configurer Auth0

Obtenez les clés de votre application

Lorsque vous vous êtes inscrit à Auth0, une nouvelle application a été créée pour vous, à moins que vous n’en ayez créé une vous-même. Vous aurez besoin de certaines informations sur cette application pour communiquer avec Auth0. Vous pouvez les trouver dans la section Application Settings du Dashboard Auth0.

Vous avez besoin des renseignements suivants :

• Domain
• Client ID
• Client Secret

Si vous téléchargez l’exemple au haut de cette page, ces renseignements seront déjà remplis pour vous.

Configurer les URL de rappel

Une URL de rappel est une URL de votre application vers laquelle Auth0 redirige l’utilisateur après son authentification. L’URL de rappel de votre application doit être ajoutée au champ Allowed Callback URLs dans les Application Settings. Si ce champ n’est pas configuré, les utilisateurs ne pourront pas se connecter à l’application et verront s’afficher une erreur.

Si vous suivez l’exemple de projet que vous avez téléchargé en haut de cette page, l’URL de rappel à ajouter au champ Allowed Callback URLs est http://127.0.0.1:3000/.

Configurer les URL de déconnexion

Une URL de déconnexion est une URL de votre application vers laquelle Auth0 peut rediriger l’utilisateur une fois qu’il est déconnecté du serveur d’autorisation. Cette URL est précisée dans le paramètre de requête returnTo. L’URL de déconnexion de votre application doit être ajoutée au champ Allowed Logout URLs dans les Application Settings. Si ce champ n’est pas défini, les utilisateurs ne pourront pas se déconnecter de l’application et une erreur s’affichera.

Si vous suivez l’exemple de projet téléchargé en haut de cette page, l’URL de déconnexion à ajouter au champ Allowed Logout URLs est http://127.0.0.1:3000.

Intégrez votre application PHP

Créons un exemple d’application qui permet d’authentifier un utilisateur dans une application PHP. Nous adopterons ici une approche simple, adaptée au format écrit. Cela dit, consultez l’application Quickstart sur GitHub pour voir un exemple plus complet.

Installation du client HTTP et des fabriques de messages

Le SDK Auth0 PHP prend en charge plusieurs normes PHP-FIG, offrant des options d’interopérabilité avec votre architecture. Deux d’entre elles sont particulièrement importantes : PSR-17 et PSR-18. Ces normes vous permettent d’intégrer les composants réseau de votre choix pour gérer les messages et les requêtes. Vous devrez installer des bibliothèques compatibles dans votre projet pour que le SDK puisse les utiliser.

La bibliothèque réseau la plus répandue pour PHP est Guzzle, bien qu’il en existe plusieurs autres dans la communauté PHP. Utilisons Guzzle pour cet exemple d’application. Encore une fois, à partir du répertoire de votre projet, exécutez la commande shell suivante :

composer require guzzlehttp/guzzle guzzlehttp/psr7 http-interop/http-factory-guzzle

Installation du SDK PHP

L’Auth0 PHP SDK nécessite Composer, un outil de gestion des dépendances pour PHP. Composer vous permet de déclarer les bibliothèques dont votre projet a besoin et les installe pour vous. Assurez-vous que Composer est installé et accessible depuis votre terminal avant de continuer.

Exécutez la commande shell suivante dans le répertoire de votre projet pour installer l’Auth0 PHP SDK :

composer require auth0/auth0-php

Cela créera un dossier vendor dans votre projet et téléchargera toutes les dépendances nécessaires pour utiliser l’Auth0 PHP SDK. Cela créera également un fichier vendor/autoload.php, utilisé dans l’exemple pour charger toutes les classes nécessaires au fonctionnement de votre application. Il est important d’inclure ce fichier d’autoload dans votre projet pour que le SDK fonctionne.

Configuration du SDK

Pour commencer, créons un fichier .env à la racine du répertoire de votre projet pour y stocker la configuration de notre application exemple et renseigner les variables d’environnement :

Comme PHP n’est pas capable de lire notre fichier .env à lui seul, nous allons installer une bibliothèque pour nous aider. Même si, pour les besoins de notre application d’exemple, nous utiliserons une bibliothèque en particulier, dans une application réelle, n’importe quel chargeur « dotenv » fera l’affaire. Depuis le répertoire de notre projet, exécutons la commande shell suivante pour installer la bibliothèque :

composer require vlucas/phpdotenv

Ensuite, créons le fichier source PHP que nous utiliserons pour ces exemples de code, index.php, et configurons une instance de l’Auth0 PHP SDK pour notre application d’exemple :

<?php

// Importation du chargeur automatique Composer pour rendre les classes du SDK accessibles :
require 'vendor/autoload.php';

// Chargement des variables d'environnement depuis le fichier .env :
(Dotenv\Dotenv::createImmutable(__DIR__))->load();

// Instanciation de la classe Auth0 avec notre configuration :
$auth0 = new \Auth0\SDK\Auth0([
    'domain' => $_ENV['AUTH0_DOMAIN'],
    'clientId' => $_ENV['AUTH0_CLIENT_ID'],
    'clientSecret' => $_ENV['AUTH0_CLIENT_SECRET'],
    'cookieSecret' => $_ENV['AUTH0_COOKIE_SECRET']
]);

Configurer les routes de votre application

Les applications PHP modernes utilisent un modèle de routage pour acheminer les requêtes HTTP entrantes vers le code chargé de les traiter, ce qui permet de déterminer ce qui doit se produire lorsque des utilisateurs visitent une “page” précise de notre application. Il n’y a pas une seule bonne façon d’implémenter le routage dans votre application, et il existe de nombreuses bibliothèques pour le faire. Pour les besoins de notre exemple d’application, nous utiliserons une bibliothèque en particulier, mais dans une application réelle, n’hésitez pas à choisir celle qui vous convient.

Depuis le répertoire de notre projet, exécutons la commande shell suivante pour installer la bibliothèque de routage :

composer require steampixel/simple-php-router

Ensuite, rouvrons notre index.php et donnons vie à notre application. Commencez par importer la bibliothèque de routage et définir, sous forme de constantes nommées, les URL complètes des routes de notre application d’exemple pour plus de commodité, car nous devrons nous y référer à quelques reprises dans l’ensemble de l’application :

// 👆 Nous continuons à partir des étapes ci-dessus. Ajoutez ceci à votre fichier index.php.

// Importez notre bibliothèque de routeur :
use Steampixel\Route;

// Définissez les constantes de route :
define('ROUTE_URL_INDEX', rtrim($_ENV['AUTH0_BASE_URL'], '/'));
define('ROUTE_URL_LOGIN', ROUTE_URL_INDEX . '/login');
define('ROUTE_URL_CALLBACK', ROUTE_URL_INDEX . '/callback');
define('ROUTE_URL_LOGOUT', ROUTE_URL_INDEX . '/logout');

Nous pouvons maintenant passer à l’ajout de la logique de routage de notre application, ainsi que des intégrations du SDK :

Vérifier s’il existe une session

L’Auth0 PHP SDK offre une méthode pratique pour vérifier si notre utilisateur est authentifié et récupérer son profil, getCredentials(). Ajoutons-la à notre route d’index pour afficher le profil de l’utilisateur s’il est connecté ou indiquer qu’il doit se connecter.

// 👆 Nous continuons à partir des étapes ci-dessus. Ajoutez ceci à votre fichier index.php.

Route::add('/', function() use ($auth0) {
  $session = $auth0->getCredentials();

  if ($session === null) {
    // L'utilisateur n'est pas connecté.
    echo '<p>Please <a href="/docs/login">log in</a>.</p>';
    return;
  }

  // L'utilisateur est connecté.
  echo '<pre>';
  print_r($session->user);
  echo '</pre>';

  echo '<p>You can now <a href="/docs/logout">log out</a>.</p>';
});

Nous pouvons accéder à toutes les propriétés du profil de notre utilisateur à partir de la propriété de réponse user, qui est un tableau. Par exemple, nous pouvons récupérer le nickname de l’utilisateur avec $session->user<a href="https://auth0.com/docs/users/user-profile-structure" target="_blank" rel="noreferrer">nickname, ou son adresse courriel à partir de $session->useremail. La structure correspond à un profil utilisateur normalisé, sur lequel vous pouvez en apprendre davantage ici.

Il est important de noter que le contenu du profil utilisateur varie selon le ou les fournisseurs d’identité sociale que vous utilisez. Vous ne devriez donc jamais présumer qu’une valeur donnée sera toujours présente dans la logique de votre application. Utilisez des constructions du langage PHP comme isset ou l’opérateur de coalescence de null pour gérer élégamment la présence ou l’absence d’une valeur, par exemple :

// ✋ Inutile d'inclure ceci dans notre exemple d'application, c'est simplement un exemple.
$name = $session->user['name'] ?? $session->user['nickname'] ?? $session->user['email'] ?? 'Unknown';

Connexion

Créons maintenant notre route /login, qui utilisera la méthode login() de l’Auth0 PHP SDK pour établir la session de l’utilisateur et renvoyer une URL personnalisée vers la Universal Login Page d’Auth0 afin de permettre à cet utilisateur de se connecter.

// 👆 Nous continuons à partir des étapes précédentes. Ajoutez ceci à votre fichier index.php.

Route::add('/login', function() use ($auth0) {
    // Il est recommandé de réinitialiser les sessions utilisateur à chaque tentative de connexion afin d'éviter les erreurs d'« état invalide », en cas de problèmes réseau ou d'autres problèmes qui interrompraient un processus de connexion en cours :
    $auth0->clear();

    // Enfin, configurez la session locale de l'application et redirigez l'utilisateur vers la page Universal Login d'Auth0 pour qu'il s'authentifie.
    header("Location: " . $auth0->login(ROUTE_URL_CALLBACK));
    exit;
});

Traitement du rappel d’authentification

Une fois que nos utilisateurs reviennent après s’être authentifiés au moyen de la Universal Login Page d’Auth0, ils sont redirigés vers la route de rappel de notre application d’exemple, /callback, que nous allons traiter à cette étape.

Quand Auth0 nous renvoie les utilisateurs, il inclut quelques paramètres essentiels dans la chaîne de requête de la requête HTTP. La méthode exchange() de l’Auth0 PHP SDK s’en charge, donc il est simple de terminer notre flux d’authentification :

// 👆 Nous continuons à partir des étapes précédentes. Ajoutez ceci à votre fichier index.php.

Route::add('/callback', function() use ($auth0) {
    // Demander au SDK de terminer le flux d'authentification :
    $auth0->exchange(ROUTE_URL_CALLBACK);

    // Enfin, rediriger l'utilisateur final vers la route d'index /, pour afficher son profil :
    header("Location: " . ROUTE_URL_INDEX);
    exit;
});

Déconnexion

Enfin, gérons correctement la déconnexion de nos utilisateurs. La méthode logout() de l’Auth0 PHP SDK s’occupe d’effacer les cookies de session de notre application exemple, de rediriger l’utilisateur vers le point de terminaison /logout d’Auth0 (ce qui met fin à la couche de session Auth0 ainsi qu’à toute couche de session du fournisseur d’identité), puis de ramener l’utilisateur vers notre route d’index /.

// 👆 Nous continuons à partir des étapes précédentes. Ajoutez ceci à votre fichier index.php.

Route::add('/logout', function() use ($auth0) {
    // Effacez la session locale de l'utilisateur dans notre application, puis redirigez-le vers le endpoint de logout d'Auth0 pour effacer sa session Auth0.
    header("Location: " . $auth0->logout(ROUTE_URL_INDEX));
    exit;
});

Lancez votre application !

Enfin, nous devons configurer notre middleware de routage pour qu’il achemine réellement les requêtes :

// 👆 Nous continuons à partir des étapes précédentes. Ajoutez ceci à votre fichier index.php.

// Ceci indique à notre routeur que nous avons terminé de configurer nos routes et que nous sommes prêts à acheminer les requêtes HTTP entrantes :
Route::run('/');

Ça y est ! Vous êtes prêt à lancer votre nouvelle application ; encore une fois, à partir du répertoire de votre projet, exécutez la commande shell suivante :

php -S 127.0.0.1:3000 index.php

Ouvrez http://127.0.0.1:3000 dans votre navigateur et essayez-le.

Que pouvez-vous faire ensuite ?

Configurer d’autres fournisseurs d’identité	Activer l’authentification multifacteur
En savoir plus sur la protection contre les attaques	En savoir plus sur les Rules
Modifier sur GitHub