README

Visa

官方 Laravel Passport 包的免费扩展。

Visa提供以下功能：

• 使用随机字符串作为客户端ID；
• 添加配置以使用UUID代替随机字符串作为客户端ID；
• 提供CheckFirstPartyClient中间件类以验证客户端为第一方客户端；
• 添加配置以使用全局Laravel错误处理器处理Passport抛出的错误，而不是Passport的内置处理器；
• 在服务提供程序中提供可重写的enableCustomGrants()方法，以简化自定义授权的注册。

Passport 兼容性

虽然此库主要遵循语义版本控制，但主版本号设置为与Passport库的主版本号对齐。这简化了确定Visa包含哪个版本的Passport。

安装

Visa已在Packagist注册，可以使用Composer安装。在命令行中运行以下命令：

composer require stratedge/visa

由于Visa扩展了Passport，安装Visa将为您安装Passport。

对于支持自动注册包的Laravel版本，Visa将自动注册自己。对于旧版本，请确保将Stratedge\Visa\VisaServiceProvider::class添加到您的config/app.php中服务提供程序的列表中。

不需要包含Passport的服务提供程序，Visa提供程序扩展了它。

从现在开始，完成所有典型的Passport安装步骤。

请注意：请参阅以下配置以确保在运行迁移之前完成任何可选的Visa配置，以确保列以正确的类型创建。

配置

要配置核心Passport功能，请参阅Passport文档。由于Visa使用Passport，您可以从Passport配置任何内容。

使用随机字符串作为客户端ID

默认情况下，Visa将使用40个字符的随机字符串作为客户端ID，与客户端密钥相同。无需配置。

使用UUID作为客户端ID

Visa也支持UUID作为客户端ID，但必须在迁移之前进行配置，以便迁移指定正确的列类型。

要使用UUID，请在AppServiceProvider的boot()方法中调用\Stratedge\Visa\Visa::enableClientUUIDs()。

<?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()
    {
        //
    }
}

使用CheckFirstPartyClient中间件

要使用CheckFirstPartyClient中间件，请将以下中间件添加到您的App\Http\Kernel类的$routeMiddleware属性中

protected $routeMiddleware = [
    'auth.first-party' => \Stratedge\Visa\Http\Middleware\CheckFirstPartyClient::class,
];

中间件可以通过密钥auth.first-party为任何路由或路由组注册。任何尝试使用分配给CheckFirstPartyClient中间件的端点进行身份验证的非第一方客户端将因身份验证错误而失败。

错误处理

默认情况下，Visa将使用内置的Passport错误处理器来自动捕获和响应错误。如果您希望禁用内置处理器并使用全局Laravel错误处理器来控制错误记录和输出，请在上AppServiceProvider的boot()方法中调用\Stratedge\Visa\Visa::disablePassportErrorHandling()。

<?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()
    {
        //
    }
}

启用自定义授权

为了使用您自己的自定义授权，您必须扩展 Stratedge\Visa\VisaServiceProvider 类，并重写 enableCustomGrants() 方法。

该方法接受一个类型为 League\OAuth2\Server\AuthorizationServer 的单个参数，它将被自动注入为参数 $server。使用 AuthorizationServer 类的 enableGrantType() 方法来启用新的授权类型。

<?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 */);
    }
}

请注意：在扩展服务提供者时，请确保在 app.php 配置文件中注册您的自定义 VisaServiceProvider，并通过您的 composer.json 文件关闭此库提供的默认提供者的自动发现功能。

扩展哲学

由于 Passport 是一个授权库，快速集成安全补丁非常重要。与创建 Passport 库的独立维护版本的分叉不同，Visa 是一个补充包，它位于您的项目中与核心 Passport 一起。从这方面来说，Visa 扩展 Passport 并仅进行最小的必要更改。

实际上，当 Visa 安装时，它将自动要求 Passport。但由于 Passport 仍然是一个独立的库，开发者可以自由指定他们希望使用的 Passport 版本。这允许开发者利用 Passport 的增量安全更新，而无需对 Visa 进行相应的更改。只要 Passport 的最新版本不进行破坏性 API 更改，更改 Passport 版本应该没问题。