stratedge / visa
A complimentary extension of the official Laravel Passport package.
Requires
- laravel/passport: ^7.0
Requires (Dev)
- kint-php/kint: ^3.0
- orchestra/testbench: ~3.7.0
- phpunit/phpunit: ^7.4
- stratedge/wye: ^0.8.0
This package is auto-updated.
Last update: 2024-10-29 05:10:56 UTC
README
Visa
A complimentary extension of the official Laravel Passport package.
Visa provides the following functionality:
- Use a random string for Client ID;
- Add configuration to use a UUID for Client ID instead of a random string;
- Provide the
CheckFirstPartyClient
middleware class to authenticate a client as a first party client; - Add configuration to use the global Laravel error handler to handle errors thrown by Passport instead of Passport's built-in handler; and
- Provide overwrite-able
enableCustomGrants()
method in the service provider to make registering custom grants easier.
Passport Compatability
While this library mostly adheres to semantic versioning, major version numbers are set to align to major versions for the Passport library. This simplifies determining which version of Visa includes which version of Passport.
Installation
Visa is registered with Packagist and can be installed with Composer. Run the following on the command line:
composer require stratedge/visa
Since Visa extends Passport, installing Visa will install Passport for you.
For versions of Laravel that support auto-registration of packages, Visa will automatically register itself. For older versions, be sure to add Stratedge\Visa\VisaServiceProvider::class
to your list of service providers in config/app.php
.
No need to include Passport's service provider, the Visa provider extends it.
From here, complete all the typical Passport installation steps.
PLEASE NOTE: See configuration below to ensure you complete any optional Visa configurations before running migrations to ensure columns are created with the correct types.
Configuration
To configure core Passport features, refer to the Passport documentation. Since Visa uses Passport, you're free to configure whatever you want from Passport.
Using Random Strings for Client ID
By default Visa will use random 40-character strings for client IDs, the same as the client secrets. No configuration required.
Using UUIDs for Client ID
Visa also supports UUIDs for client IDs, but must be configured to do so before migrations are run so that the migrations specify the correct column type for client_id
.
To use UUIDs, call \Stratedge\Visa\Visa::enableClientUUIDs()
in the boot()
method of your AppServiceProvider
:
<?php namespace App\Providers; use Illuminate\Support\ServiceProvider; use Stratedge\Visa\Visa; class AppServiceProvider extends ServiceProvider { /** * Bootstrap any application services. * * @return void */ public function boot() { // Configure UUIDs for OAuth client IDs Visa::enableClientUUIDs(); } /** * Register any application services. * * @return void */ public function register() { // } }
Using the CheckFirstPartyClient
Middleware
To use the CheckFirstPartyClient
middleware, add the following middleware to the $routeMiddleware
property of your App\Http\Kernel
class:
protected $routeMiddleware = [ 'auth.first-party' => \Stratedge\Visa\Http\Middleware\CheckFirstPartyClient::class, ];
The middleware can then be registered for any route or route group with the key auth.first-party
. Any clients that are not considered first-party that attempt to authenticate with endpoints assigned the CheckFirstPartyClient
middleware will fail with an authentication error.
Error Handling
By default, Visa will use the built-in Passport error handler that will catch and respond to errors automatically. If you wish to disable the built-in handler and use the global Laravel error handler to control the logging and output of errors, call \Stratedge\Visa\Visa::disablePassportErrorHandling()
in the boot()
method of your AppServiceProvider
:
<?php namespace App\Providers; use Illuminate\Support\ServiceProvider; use Stratedge\Visa\Visa; class AppServiceProvider extends ServiceProvider { /** * Bootstrap any application services. * * @return void */ public function boot() { // Do not use the standard Passport error handling Visa::disablePassportErrorHandling(); } /** * Register any application services. * * @return void */ public function register() { // } }
Enabling Custom Grants
In order to use your own custom grants, you must extend the Stratedge\Visa\VisaServiceProvider
class and overload the enableCustomGrants()
method.
The method accepts a single parameter of type League\OAuth2\Server\AuthorizationServer
that will be injected automatically as the argument $server
. Use the enableGrantType()
method of the AuthorizationServer
class to enable new grant types.
<?php namespace App\Providers; use Stratedge\Visa\VisaServiceProvider as BaseProvider; class VisaServiceProvider extends BaseProvider { /** * Enables any additional custom grants when overloaded. * * @param AuthorizationServer $server * @return void */ public function enableCustomGrants(AuthorizationServer $server) { $server->enableGrantType(/* Register custom grant here */); } }
PLEASE NOTE: When extending the service provider, be sure to register your custom
VisaServiceProvider
in theapp.php
configuration file and turn off the auto-discovery of the default provider provided by this library through yourcomposer.json
file.
Extension Philosophy
Because Passport is an authorization library, integrating security patches quickly is immensely important. Unlike a fork, which creates a separately maintained version of the entire Passport library, Visa is a complimentary package that sits alongside the core Passport in your project. In that sense Visa extends Passport and makes only the smallest required changes.
In fact, when Visa is installed it will automatically require Passport. But since Passport remains a separate library, the developer is free to specify the version of Passport they wish to use. This allows the developer to take advantage of incremental security updates in Passport without requiring corresponding changes to Visa. So long as the newest version of Passport makes no breaking API changes, changing the Passport version should work just fine.