Authentification JWT avec Policier

Introduction

Policier permet de valider les requêtes via JWT (JSON Web Tokens).

Installation

Pour installer le package, vous devez utiliser composer (gestionnaire de paquets PHP) comme ceci :

composer require bowphp/policier

Configuration

Vous pouvez regarder toutes les options de configuration ici.

config/policier.php

return [
  /**
   * Heure d'expiration du token
   */
  "exp" => 3600,

  /**
   * Le token est utilisable après cette heure
   */
  "nbf" => 60,

  /**
   * Le token était émis
   */
  "iat" => 60,

  /**
   * Configure l'émetteur
   */
  "iss" => "localhost",

  /**
   * Configure le public
   */
  "aud" => "localhost",

  /**
   * Algorithme de hachage utilisé
   *
   * HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512,
   */
  "alg" => "HS512",

  /**
   * Votre Signature, ce champs est obligatoire pour les autres type de hachage sauf RSA
   */
  'signkey' => null,

  /**
   * Signature en utilisant votre RSA, ce qui se chargera automatiquement si la clé de hachage est de type RSA
   */
  "keychain" => [
    /**
     * Chemin vers votre clé privée
     */
    "private" => null,

    /**
     * Chemin vers votre clé publique
     */
    "public" => null
  ]
];

Utilisation

Policier est très simple d'utilisation et possède une API claire. La configuration retourne un singleton.

use Policier\Policier;

$configure = require "/path/to/config/file.php";

$policier = Policier::configure($configure);

Vous pouvez aussi faire comme ceci:

use Policier\Policier;

$configure = require "/path/to/config/file.php";

Policier::configure($configure);

$policier = Policier::getInstance();

Après la configuration, vous pouvez utiliser le helper policier :

policier($action, ...$args);

Actions disponibles

La valeur d'action doit être l'une de ces valeurs : encode, decode, parse, verify, validate.

Mise à jour ou Récupération de la configuration

Mise à jour de la Configuration

Vous pouvez mettre à jour la configuration de base avec la méthode setConfig. Elle prend un tableau de clés à fusionner avec la configuration existante :

$policier->setConfig([
  'exp' => time() + 72000,
  'iss' => 'api.example.com',
]);

Récupération de la Configuration

Vous pouvez également obtenir les informations de configuration avec la méthode getConfig:

$policier->getConfig('exp');

Encoder un Token

Encoder rapidement un token:

$id = uniqid();

$claims = [
  "name" => "Franck",
  "nickname" => "papac",
  "logged" => true
];

$token = $policier->encode($id, $claims);

$token->expireIn(); // Expired In
$token->getToken(); // Token value

echo $token;
//=> eyJ0eX...OiJKV1.eyJpc3Mi...OiJsb2.l7v0bS0r...qnK1IeR

Instance Token

$token est une instance de Policier\Token et implémente la méthode magique __toString. Vous pouvez obtenir l'heure d'expiration avec expireIn et getToken pour prendre la valeur du token.

Via l'assistant:

policier('encode', $id, $claims);

Décoder un Token

decode() retourne une instance de Policier\Token. Utilisez ses méthodes getHeaders() / getHeader($name) / getClaim($name) / getClaims() pour en extraire les informations :

$result = $policier->decode($token);

$result->getHeaders();          // array
echo $result->getClaim('name'); // => Franck

Via l'assistant:

policier('decode', $token);

Transformer un Token

$token = $policier->parse($token);

$token->hasHeader("old") // Vérifier si l'en-tête existe
$token->getHeader("alg", $default = null); // Obtenez un en-tête
$token->getHeaders(); // Obtenir tous les en-têtes

$token->hasClaim("name") // Vérifier si la réclamation existe
$token->getClaim("name", $default = null); // Obtenez une réclamation
$token->getClaims(); // Obtenez toutes les réclamations

$token->isExpired(); // Vérifier si le token a expiré

echo $token->getClaim("name");
//=> Franck

Via l'assistant:

policier('parse', $token);

Vérifier un Token

Vérifier si le jeton est valide avec tous les attributs JWT.

$verified = $policier->verify($token);

if ($verified) {
  echo "Token est valide";
} else {
  echo "Token n'est pas valide";
}

Via l'assistant:

policier('verify', $token);

Valider un Token

Vérifiez à la fois la signature du jeton et qu'il appartient bien à un sujet donné (le même $id que vous avez passé à encode()). La méthode validate prend en deuxième argument cet identifiant — pas un tableau de claims.

$id = $token->getClaim('jti'); // ou tout autre identifiant que vous avez utilisé

$validated = $policier->validate((string) $token, $id);

if ($validated) {
  echo "Token valide pour le sujet {$id}";
} else {
  echo "Token invalide ou expiré";
}

Via l'assistant:

policier('validate', $token, $id);

Vérification des claims arbitraires

Si vous voulez aussi confronter des claims côté application (nom, rôle, etc.), faites la comparaison vous-même après decode() :

$decoded = $policier->decode($token);
if ($decoded->getClaim('nickname') !== 'papac') {
  // claim inattendu
}

BowPHP et Policier

Si vous utilisez BowPHP, vous pouvez utiliser le plugin de configuration Policier\Bow\PolicierConfiguration::class et le middleware Policier\Bow\PolicierMiddleware::class.

Relier la configuration sur app\Kernel.php :

app\Kernel.php

public function middlewares()
{
  return [
    ...
    'policier' => \Policier\Bow\PolicierMiddleware::class,
    ...
  ];
}

public function configurations()
{
  return [
    ...
    \Policier\Bow\PolicierConfiguration::class,
    ...
  ];
}

Utilisez le middleware:

$app->get('/api', function () {
  $token  = policier()->getToken();
})->middleware('policier');

Le token a été analysé dans l'instance de Policier dans le processus middleware via la méthode plug. Après l'exécution du middleware, vous pouvez:

• Obtenez le token avec getToken
• Décoder le token avec getDecodeToken
• Analyser le token avec getParsedToken

Personnalisation du Middleware

Personnalisation avancée

Vous pouvez créer un autre middleware qui étendra le middleware par défaut Policier\Bow\PolicierMiddleware::class. Ce qui vous donne la possibilité de changer les messages d'erreur en surchargeant les méthodes getUnauthorizedMessage, getExpirationMessage, getExpirationStatusCode et getUnauthorizedStatusCode.

php bow add:middleware CustomPolicierMiddleware

Et ensuite, vous pouvez faire ceci :

use Bow\Http\Request;
use Policier\Bow\PolicierMiddleware;

class CustomPolicierMiddleware extends PolicierMiddleware
{
  /**
   * Obtenir le message d'erreur
   *
   * @return array
   */
  public function getUnauthorizedMessage()
  {
    return [
      'message' => 'unauthorized',
      'error' => true
    ];
  }

  /**
   * Obtenir le message d'expiration du token
   *
   * @return array
   */
  public function getExpirationMessage()
  {
    return [
      'message' => 'token is expired',
      'expired' => true,
      'error' => true
    ];
  }

  /**
   * Obtenir le code de réponse non autorisé
   *
   * @return int
   */
  public function getUnauthorizedStatusCode()
  {
    return 403;
  }

  /**
   * Obtenir le code de réponse pour l'expiration
   *
   * @return int
   */
  public function getExpirationStatusCode()
  {
    return 403;
  }
}

Publier le middleware

Publication du middleware personnalisé

Pour publier le middleware personnalisé et écraser celui par défaut de Policier, il suffit d'ajouter le middleware dans le fichier app/Kernel.php avec la clé policier.

public function middlewares()
{
  return [
    ...
    'policier' => \App\Middleware\CustomPolicierMiddleware::class,
    ...
  ];
}

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.