Skip to content

Latest commit

 

History

History
406 lines (298 loc) · 9.04 KB

fr.md

File metadata and controls

406 lines (298 loc) · 9.04 KB
Raw

Policier permet de valider la demande via JWT

Installation

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;
//=> eyJ0eXAiOiJKV1QiLCJhbGciOiI6IjEifQ.eyJpc3MiOiJsb2NhbGhvc3QiLCJhdWQiOiJsb2NhbGhvc3QiLCJqdGkiOi.l7v0bS0rqnK1IeRGRBTFIH5s2TN9KtgD7BLivApq

$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.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 getInvalidMessage()
  {
    return 'Token est invalide';
  }

  /**
   * Obtenir le message d'expiration du token
   *
   * @return array
   */
  public function getExpirationMessage()
  {
    return 'Token a expiré';
  }
}

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.php avec la clé api.

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

Laravel et Policier

Si vous utilisez Laravel, vous pouvez charger le service provider Policier\Laravel\PolicierServiceProvider::class et lié le middleware Policier\Laravel\PolicierMiddleware::class. La liaison peut être faire n'import quel nom, ici jwt.

Publier le Service provider de Policier

"providers" => [
  \Policier\Laravel\PolicierServiceProvider::class,
]

Publier la Facade de Policier

"aliases" => [
  'Policier' => \Policier\Laravel\Policier::class,
]

Publier le Middleware de Policer

protected $routeMiddleware = [
  'policier' => \Policier\Laravel\PolicierMiddleware::class,
]

Utilisation du middleware

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

Vous pouvez aussi modifer les messages d'erreurs et code http de ces message en etendant le middleware comme nous avons faire avec Bow Framework.

php artisan make:middleware CustomPolicierMiddleware

et ensuite vous pouvez faire ceci:

Vous devez publier le middleware dans le fichier app\Http\Kernel.php.

N'hésitez pas à donner votre avis sur la qualité de la documentation ou proposez des correctifs.