API PHP

Par Evan Sims

Ce guide explique comment intégrer Auth0 à une API backend 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écouvrez Auth0? Découvrez comment fonctionne Auth0 et apprenez-en davantage sur l’implémentation de l’authentification et de l’autorisation des API à l’aide du framework OAuth 2.0.

Configurer les API Auth0

Créer une API

Dans la section APIs du tableau de bord Auth0, cliquez sur Create API. Saisissez un nom et un identifiant pour votre API, par exemple https://quickstarts/api. Vous utiliserez ensuite cet identifiant comme audience lors de la configuration de la vérification du jeton d’accès. Laissez Signing Algorithm à RS256.

Par défaut, votre API utilise RS256 comme algorithme de signature des jetons. Comme RS256 utilise une paire de clés privée et publique, les jetons sont vérifiés à l’aide de la clé publique de votre compte Auth0. La clé publique est au format JSON Web Key Set (JWKS) et peut être consultée ici.

Définir les permissions

Les permissions vous permettent de définir comment les ressources peuvent être consultées au nom de l’utilisateur à l’aide d’un jeton d’accès donné. Par exemple, vous pourriez choisir d’accorder un accès en lecture à la ressource messages si les utilisateurs ont le niveau d’accès Manager, et un accès en écriture à cette ressource s’ils ont le niveau d’accès administrateur.

Vous pouvez définir les permissions autorisées dans la vue Permissions de la section APIs de l’Auth0 Dashboard.

Cet exemple utilise le scope read:messages.

Cet exemple montre :

• Comment vérifier la présence d’un JSON Web Token (JWT) dans l’en-tête Authorization d’une requête HTTP entrante.
• Comment vérifier si le jeton est valide à l’aide du JSON Web Key Set (JWKS) de votre compte Auth0. Pour en savoir plus sur la validation des jetons d’accès, consultez Valider les jetons d’accès.

Intégration de votre API backend PHP

Créons un exemple d’application qui utilise une API backend écrite en PHP pour autoriser un jeton signé par Auth0. Nous adopterons ici une approche simple, adaptée au format de cette documentation. Cela dit, consultez l’application Quickstart sur GitHub pour un exemple plus complet.

Installation du client HTTP et des fabriques de messages

Le SDK Auth0 PHP prend en charge de nombreuses normes PHP-FIG afin d’offrir une interopérabilité maximale avec l’architecture de votre projet, mais deux d’entre elles sont particulièrement importantes : PSR-17 et PSR-18. Ces normes vous permettent de « brancher » les composants réseau de votre choix pour gérer la messagerie et les requête. Vous devrez installer des bibliothèques compatibles dans votre projet pour que le SDK puisse les utiliser.

Guzzle est la bibliothèque réseau la plus répandue pour PHP, bien qu’il en existe plusieurs autres dans la communauté PHP. Utilisons Guzzle pour cet exemple d’application :

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

Installation du SDK PHP

L’Auth0 PHP SDK requiert Composer, un outil de gestion des dépendances en PHP. Composer vous permet de déclarer les bibliothèques dont votre projet dépend et les installe pour vous. Assurez-vous que Composer est installé et accessible à partir de votre shell 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 aussi un fichier vendor/autoload.php, utilisé dans l’exemple pour charger toutes les classes nécessaires au bon fonctionnement de votre application. Il est important d’inclure ce fichier de chargement automatique dans votre projet pour que le SDK fonctionne.

Configurer le 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, puis renseignons les variables d’environnement :

Comme PHP ne peut pas lire à lui seul notre fichier .env, nous allons installer une bibliothèque pour nous y aider. Même si nous utiliserons une bibliothèque précise pour les besoins de notre application exemple, n’importe quel chargeur « dotenv » conviendra dans une application réelle. À partir du 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 de nos 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([
    'strategy' => \Auth0\SDK\Configuration\SdkConfiguration::STRATEGY_API,
    'domain' => $_ENV['AUTH0_DOMAIN'],
    'clientId' => $_ENV['AUTH0_CLIENT_ID'],
    'clientSecret' => $_ENV['AUTH0_CLIENT_SECRET'],
    'audience' => ($_ENV['AUTH0_AUDIENCE'] ?? null) !== null ? [trim($_ENV['AUTH0_AUDIENCE'])] : null,
]);

Authentifier l’utilisateur

Pour cet exemple d’application, nous nous concentrons sur l’autorisation. Il existe de nombreuses façons d’authentifier vos utilisateurs avant qu’ils n’accèdent à votre API backend pour l’autorisation, par exemple en utilisant la bibliothèque SPA.js d’Auth0. Cette approche est présentée dans ce projet Github qui accompagne l’application Quickstart. Quelle que soit l’approche choisie, pour fonctionner, cet exemple d’application s’attend à ce que vous lui transmettiez votre jeton d’accès au moyen d’un paramètre de requête ou d’un en-tête.

Autoriser un jeton d’accès

D’abord, nous devons extraire le JSON Web Token (JWT) de la requête HTTP entrante. Recherchons un paramètre ?token dans une requête GET, ou un en-tête HTTP_AUTHORIZATION ou Authorization.

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

$jwt = $_GET['token'] ?? $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['Authorization'] ?? null;

Ensuite, décodons le jeton, s’il est présent :

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

// Si un jeton est présent, le traiter.
if ($jwt !== null) {
    // Supprimer les espaces en début et fin de la chaîne du jeton.
    $jwt = trim($jwt);

    // Supprimer le préfixe 'Bearer ' s'il est présent, au cas où l'en-tête Authorization le contiendrait.
    if (substr($jwt, 0, 7) === 'Bearer ') {
        $jwt = substr($jwt, 7);
    }

    // Tenter de décoder le jeton :
    try {
        $token = $auth0->decode($jwt, null, null, null, null, null, null, \Auth0\SDK\Token::TYPE_TOKEN);
        define('ENDPOINT_AUTHORIZED', true);
    } catch (\Auth0\SDK\Exception\InvalidTokenException $exception) {
        // Le jeton n'était pas valide. Affichons le message d'erreur provenant du Auth0 SDK.
        // Dans une application réelle, on voudrait probablement afficher une erreur personnalisée ici.
        die($exception->getMessage());
    }
}

Selon la manière dont vous configurez le routage de votre API, la façon précise d’intégrer ces vérifications peut varier légèrement, mais le principe reste le même : vérifiez le jeton et, si votre API endpoint exige une autorisation, rejetez l’accès si le jeton n’est pas valide ou acceptable :

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

// La requête est-elle autorisée ?
if (defined('ENDPOINT_AUTHORIZED')) {
    // Répondre avec une réponse JSON :
    echo json_encode([
        'authorized' => true,
        'data' => $token->toArray()
    ], JSON_PRETTY_PRINT);

    exit;
}

// Retourner un statut HTTP 401 Non autorisé :
http_response_code(401);

// Répondre avec une réponse JSON :
echo json_encode([
    'authorized' => false,
    'error' => [
        'message' => 'You are NOT authorized to be here!'
    ]
], JSON_PRETTY_PRINT);

Mise en cache

Cela fonctionne, mais dans une application réelle, nous voudrons utiliser la mise en cache pour éviter d’atteindre les limites de taux d’Auth0 ou de ralentir notre application avec des requêtes réseau inutiles. L’Auth0 PHP SDK prend en charge une interface de mise en cache appelée PSR-6, à laquelle vous pouvez brancher n’importe quelle bibliothèque de mise en cache compatible, afin que le SDK s’intègre naturellement à votre architecture.

Pour notre exemple, utilisons la bibliothèque du composant de cache Symfony. À partir du répertoire racine de notre projet, exécutez la commande shell suivante :

composer require symfony/cache

Ensuite, nous devons mettre à jour notre SdkConfiguration pour que le SDK l’utilise :

// ✋ Insérez ceci AVANT la gestion du jeton ajoutée à l'étape ci-dessus, afin que le SDK utilise le cache.

$tokenCache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
$auth0->configuration()->setTokenCache($tokenCache);

Notre application d’exemple mettra maintenant en cache les requêtes réseau liées aux jetons.

Que pouvez-vous faire ensuite ?

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

---