mathieu-bour / guardian
Highly configurable JSON Web Token implementation for Laravel and Lumen.
Installs: 1 627
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 1
Forks: 1
Open Issues: 17
Requires
- php: ^7.2
- ext-json: *
- ext-sodium: *
- illuminate/auth: ^6.0 || ^7.0
- illuminate/http: ^6.0 || ^7.0
- illuminate/support: ^6.0 || ^7.0
- psr/log: ^1.1
- ramsey/uuid: ^3.0 || ^4.0
- web-token/jwt-checker: ^2.1
- web-token/jwt-core: ^2.1
- web-token/jwt-key-mgmt: ^2.1
Requires (Dev)
- laravel/framework: ^7.0
- laravel/lumen-framework: ^7.0
- mathrix-education/coding-standard: 2.0.1
- mockery/mockery: ^1.3
- phpbench/phpbench: ^0.17.0
- phpunit/phpunit: ^8.0
- web-token/jwt-signature-algorithm-ecdsa: ^2.1
- web-token/jwt-signature-algorithm-eddsa: ^2.1
- web-token/jwt-signature-algorithm-hmac: ^2.1
- web-token/jwt-signature-algorithm-rsa: ^2.1
Suggests
- ext-gmp: Required to use the ECDSA and EDDSA keys.
- web-token/jwt-signature-algorithm-ecdsa: Sign tokens using Elliptic Curves.
- web-token/jwt-signature-algorithm-eddsa: Sign tokens using Edwards-curve.
- web-token/jwt-signature-algorithm-hmac: Sign tokens using HMAC.
- web-token/jwt-signature-algorithm-rsa: Sign tokens using RSA.
- dev-main
- 0.1.0
- 0.1.0-rc.2
- 0.1.0-rc.1
- 0.1.0-beta.5
- 0.1.0-beta.4
- 0.1.0-beta.3
- 0.1.0-beta.2
- 0.1.0-beta.1
- dev-dependabot/npm_and_yarn/docs/terser-4.8.1
- dev-dependabot/npm_and_yarn/docs/mermaid-9.1.2
- dev-dependabot/npm_and_yarn/docs/eventsource-1.1.1
- dev-dependabot/npm_and_yarn/docs/color-string-1.9.1
- dev-dependabot/npm_and_yarn/docs/postcss-7.0.39
- dev-dependabot/npm_and_yarn/docs/async-2.6.4
- dev-dependabot/npm_and_yarn/docs/minimist-1.2.6
- dev-dependabot/npm_and_yarn/docs/url-parse-1.5.10
- dev-dependabot/npm_and_yarn/docs/prismjs-1.27.0
- dev-dependabot/npm_and_yarn/docs/follow-redirects-1.14.8
- dev-dependabot/npm_and_yarn/docs/path-parse-1.0.7
- dev-dependabot/npm_and_yarn/docs/ws-6.2.2
- dev-dependabot/npm_and_yarn/docs/dns-packet-1.3.4
- dev-dependabot/npm_and_yarn/docs/browserslist-4.16.6
- dev-dependabot/npm_and_yarn/docs/lodash-4.17.21
- dev-dependabot/npm_and_yarn/docs/ssri-6.0.2
- dev-dependabot/npm_and_yarn/docs/http-proxy-1.18.1
This package is auto-updated.
Last update: 2022-08-21 01:08:58 UTC
README
Highly configurable JSON Web Token implementation for Laravel and Lumen.
Guardian exposes an additional authentication guardian
driver, which can be used like the standard session
or token
drivers.
Guardian follows the Semantic Versioning specification.
❗ The master
branch should not be considered stable prior to the 1.0.0 release. ❗
Motivations
Our company based its back-end on the Lumen Framework and we needed a stateless identification and authentication method. We chose to use the JSON Web Tokens which combines security and ease. While some libraries exist like tymondesigns/jwt-auth or laravel/passport, they did not meet our requirements. Indeed, we wanted to have control over the cryptographic algorithms of the keys as well as to be able to use several of them.
After careful consideration, we decided to develop our own JWT library for Lumen which was later ported to Laravel and shared open-source.
Acknowledgements
- Rafhael Cedeno and Laura Bannier for their English reviews
- JWT cryptography implementation by
web-token
- Benchmarks ran using PHPBench
- Documentation generated by VuePress
- Tests ran using PHPUnit and Mockery
Prerequisites
- PHP >= 7.2
- Laravel/Lumen 6 or 7
Installation
Simply add Guardian to your project dependencies.
composer require mathieu-bour/guardian
Depending on the algorithm you want to use, install the corresponding cryptographic library:
Algorithm | Library | Required PHP extensions |
---|---|---|
ECDSA | web-token/jwt-signature-algorithm-ecdsa |
openssl |
EdDSA | web-token/jwt-signature-algorithm-eddsa |
sodium |
HMAC | web-token/jwt-signature-algorithm-hmac |
n/a |
RSA | web-token/jwt-signature-algorithm-rsa |
openssl, gmp |
If you do not know which algorithm to choose, we recommend ECDSA
with the ES512
algorithm and the P-521
curve.
Laravel
Publish the default Guardian configuration:
php artisan vendor:publish --provider="Windy\Guardian\GuardianServiceProvider"
Lumen
Copy the default Guardian configuration from vendor/mathieu-bour/guardian/config/guardian.php
to config/guardian.php
.
Then, add the provider to your bootstrap/app.php
and load the configuration with:
$app->configure('guardian'); $app->register(Windy\Guardian\GuardianServiceProvider::class);
If you want to use the Guardian
Facade, ensure that the application is loaded with Facades in your bootstrap/app.php
.
$app->withFacades();
Next steps
- Learn more about JWT
- Read the configuration reference
- Read our tutorial on users authentication
Alternatives
Here, we humbly refer to the alternatives to Guardian that we found interesting.
laravel/passport
Passport is the official Laravel library which supports JWT authentication.
Laravel makes API authentication a breeze using Laravel Passport, which provides a full OAuth2 server implementation for your Laravel application in a matter of minutes.
tymondesigns/jwt-auth
jwt-auth is a worthwhile alternative to Guardian which provides a higher-level API, such as authenticating users directly from the request credentials via a Facade. jwt-auth also provides a way to blacklist the generated tokens whereas Guardian leaves the implementation to the developer. If you are looking for a simpler way to use JWT, we highly recommend that you take a look to this library!