🔐 Policier JWT Auth

• Installation
• Configuration
• Utilisation
  • Mise à jour ou Récupération de la configuration
    • Mise à jour de la Configuration
    • Récupération de la Configuration
  • Encoder un Token
  • Décoder un Token
  • Transformer un Token
  • Vérifier un Token
  • Valider un Token
• Bow Framework et Policier
  • Personnalisation du Middleware
    • Publier le middleware

Installation

Policier permet de valider la demande via JWT

Pour installer la stratégie d'installation, vous devez utiliser composer (gestionnaire de paquets PHP) comme ceci.

composer require bowphp/policier

Configuration

Vous pouvez regarder toutes les options de configuration ici.

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 chargera automatique si la clé de hashage 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 une 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);

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:

$policier->setConfig('exp', time() + 72000);

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

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

Via l'assistant:

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

Décoder un Token

Même chose pour le décodage de token:

$result = $policier->decode($token);
$result['headers'];

echo $result['claims']['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

Validez le jeton avec les informations de réclamation et les informations exp.

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

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

if ($validated) {
  echo "Les informations sont valides";
} else {
  echo "Les informations ne sont pas valides";
}

Via l'assistant:

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

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

Bow Framework et Policier

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

Relier la configuration sur app\Kernel\Loader.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

Notez que vous pouvez créer un autre middleware qui étendra le middleware par defaut Policier\Bow\PolicierMiddleware::class. Ce qui vous donne la possibilité de changer les messages d'erreur en surchargant les methodes getUnauthorizedMessage, getExpirateMessage, getExpirateCode et getUnauthorizedCode.

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
   *
   * @return int
   */
  public function getExpirationStatusCode()
  {
    return 403;
  }
}

Publier le middleware

Pour publier le middleware personnalisé et écraser celui par defaut de Policier c'est très simple, il suffit seulement d'ajouter le middleware dans le fichier app/Kernel/Loader.php avec la clé api.

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.