README

关于

使用此插件将最新和简单的 Socialite 支持添加到您的 Filament 管理面板。为登录页面添加 OAuth 按钮。

理想适用于寻求简单 OAuth 集成的 Laravel 和 Filament 用户。

警告

Socialment 目前处于测试版。请报告您遇到的所有问题。

如果您选择在生产环境中使用此包，请谨慎行事。

迄今为止，唯一经过测试的提供者是 Azure AD。

参考文献

此包扩展了 Laravel Socialite。Socialite 目前支持 Facebook、Twitter、LinkedIn、Google、GitHub、GitLab 和 Bitbucket 的认证。

有关如何配置应用程序以使用这些提供者的更多信息，请参阅 Socialite 文档。

许多其他提供者可通过 Socialite Providers 网站获得。有关如何配置应用程序以使用它们的信息，请参阅每个提供者的文档。

演示

有关此包的示例用法，请参阅 ChrisReedIO/Socialment-Demo。

安装

您可以通过 composer 安装此包

composer require chrisreedio/socialment

使用

初始设置

您可以通过运行以下命令轻松完成初始设置

php artisan socialment:install

此外，编辑您的面板的 tailwind.config.js 内容部分，包括以下内容的最后一行

    content: [
    "./app/Filament/**/*.php",
    "./resources/views/filament/**/*.blade.php",
    "./vendor/filament/**/*.blade.php",
    // ... Other Content Paths

    // Ensure the line below is listed!!!
    "./vendor/chrisreedio/socialment/resources/**/*.blade.php",
],

如果忘记此步骤，则插件样式将不会应用。

请继续到下一部分以继续设置过程。

面板配置

将此插件包含在您的面板配置中

$panel
	->plugins([
		// ... Other Plugins
        \ChrisReedIO\Socialment\SocialmentPlugin::make(),        
	])

提供者配置

重要

在此阶段，您需要配置应用程序以使用您想要支持的提供者。

要么配置所需的库存 socialite 提供者，要么配置 社区维护的提供者。

有关更多信息，请参阅 Socialite 文档。

这通常涉及安装包并配置应用程序的 config/services.php 文件。

Socialment 配置

提供者配置

警告

此提供者配置方法已弃用，将在未来版本中删除。

在您的 面板配置 中配置提供者有许多优点，是推荐的方法。

无论您是使用默认提供者还是添加自己的提供者，您都需要在 socialment.php 配置文件中配置它们。

按照以下格式配置 socialment.php 配置文件以指定提供者

return [
    'providers' => [
        'azure' => [
            'icon' => 'fab-microsoft', // Font Awesome Brand Icon
            'label' => 'Azure', // Display Name on the Login Page
        ]
    ],
	// ... Other Configuration Parameters
];

配置文件中指定的提供者适用于所有面板。

按面板配置提供者

您应该在每面板的基础上指定提供者。为此，请使用插件的 ->registerProvider 方法。

$panel->plugins([
    \ChrisReedIO\Socialment\SocialmentPlugin::make()
        ->registerProvider('azure', 'fab-microsoft', 'Azure Active Directory'),
]);

示例提供者配置 - Azure Active Directory

重要

对于此配置的Azure提供程序，重定向URI将是 https://DOMAIN/login/azure/redirect

回调URI将是 https://DOMAIN/login/azure/callback

例如，库存中的 socialment.php 配置中包含的示例提供程序是Azure Active Directory。要开始，请参考Azure Socialite提供程序的文档。

通常，您会遵循上述链接中的提供程序文档，但为了演示Socialment的过程，我将在此包含步骤。

根据其文档，您将通过以下方式安装社区Azure提供程序：

composer require socialiteproviders/microsoft-azure

然后您需要配置您的 config/services.php 文件以包含Azure提供程序的凭证

'azure' => [    
  'client_id' => env('AZURE_CLIENT_ID'),
  'client_secret' => env('AZURE_CLIENT_SECRET'),
  'redirect' => env('AZURE_REDIRECT_URI'),
  'tenant' => env('AZURE_TENANT_ID'),
  'proxy' => env('PROXY')  // optionally
],

此外，您需要将此提供程序的事件监听器添加到您的 app/Providers/EventServiceProvider.php 文件中

protected $listen = [
	// ... other listeners

    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        // ... other providers
        \SocialiteProviders\Azure\AzureExtendSocialite::class.'@handle',
    ],
];

最后，别忘了将所需的环境变量添加到您的 .env 文件中

AZURE_CLIENT_ID=
AZURE_CLIENT_SECRET=
AZURE_REDIRECT_URI=
AZURE_TENANT_ID=

通常可以忽略 usage 部分，因为这是此包应该为您处理的主要部分。

注意

计划改进对登录过程的处理，使其与Socialstream更一致，允许您指定一个action类或闭包来处理登录过程。

这将允许针对每个提供程序、每个应用程序进行自定义处理。

此包还使用了Blade Font Awesome包，由Owen Voke提供。

在Font Awesome网站上搜索品牌图标。

可见性覆盖

默认情况下，该插件在登录表单底部显示配置的提供程序。您还可以通过传递布尔值或闭包到visible方法来覆盖插件的可视性

$panel->plugins([
    \ChrisReedIO\Socialment\SocialmentPlugin::make()
        ->visible(fn () => false)
]);

附加内容

您可以使用以下方式发布和自定义视图：

php artisan vendor:publish --tag="socialment-views"

登录回调

您可以通过向服务提供者的boot方法添加类似以下代码的代码来配置预/后登录钩子/回调

use ChrisReedIO\Socialment\Models\ConnectedAccount;

public function boot(): void
{
    // Post Login Hook
    Socialment::preLogin(function (ConnectedAccount $connectedAccount) {
        // Handle custom pre login logic here.
    });
    
    // Multiple hooks can be added
    Socialment::preLogin(function (ConnectedAccount $connectedAccount) {
        // Handle additional custom pre login logic here if you need.
    });

    // Post Login Hook
    Socialment::postLogin(function (ConnectedAccount $connectedAccount) {
        // Handle custom post login logic here.
        Log::info('User logged in with ' . $connectedAccount->provider . ' account', [
            'connectedAccount' => $connectedAccount,
        ]);
    });
}

可以通过$connectedAccount->user访问用户关系。

使用ConnectedAccount而不是User，这样您可以轻松知道哪个社交账户用于登录。

失败的登录路由

如果登录失败或遇到InvalidStateException，用户将被重定向到配置的loginRoute路由。

默认为filament.admin.auth.login，但可以在面板提供程序配置中覆盖该插件声明。

$panel->plugins([
    \ChrisReedIO\Socialment\SocialmentPlugin::make()
        ->loginRoute('filament.staff.auth.login')
]);

您还可以在此处使用闭包来动态设置路由

$panel->plugins([
    \ChrisReedIO\Socialment\SocialmentPlugin::make()
        ->loginRoute(fn () => SomeFunctionToGetTheRouteName())
]);

配置

这是发布配置文件的内容

return [
    'view' => [
        // Set the text above the provider list
        'prompt' => 'Or Login Via',
        // Or change out the view completely with your own
        'providers-list' => 'socialment::providers-list',
    ],
    
    // DEPRECATED: This will be removed in a future version.
    // Configure routes via the panel provider.
    'routes' => [
        'home' => 'filament.admin.pages.dashboard',
    ],
    
    'models' => [
        // If you want to use a custom user model, you can specify it here.
        'user' => \App\Models\User::class,
    ],
    
    // DEPRECATED: This will be removed in a future version.
    // Configure providers via the panel provider.
    'providers' => [
        'azure' => [
            'icon' => 'fab-microsoft',
            'label' => 'Azure Active Directory',
        ]
    ],
];

前端SPA认证

注意

此功能仍在开发中，因此高度实验性。

预计会有破坏性更改和错误。请自行承担风险。

随着功能的最终确定，文档将得到更新。

此功能将来可能被拆分为单独的包。

此包包括使用单页应用程序（SPA）前端进行认证的支持。Filament后端和SPA前端必须托管在同一域上。

登录会话是共享的，因此登录SPA或后端都会同时登录。

需要特殊CORS和会话设置才能使其工作，并必须小心确保适当的访问控制（策略/面板访问等）到位。

设置

您需要将新的spaAuth路由添加到您的routes/web文件中。

// In this example, we pass 'dashboard' as the SPA route name.
// We'll want to make sure the 'prefix' our custom routes match.
// If no prefix is set/passed to spaAuth, the default is 'spa'.

Route::spaAuth('dashboard');

Route::middleware('auth:sanctum')
    ->prefix('dashboard')
    ->as('dashboard.')
    ->group(function () {
        // Custom Routes
    });

配置更改

您需要修改config/cors.php文件。

您需要在paths数组中添加以下内容

    'paths' => [
        // ... Other Paths
        'spa/*', // OR use the custom prefix you set in the routes/web file.
    ],

同时确保supports_credentials设置为true

    'supports_credentials' => true,

环境变量

我们需要设置一些ENV变量以确保SPA认证正常工作。

SANCTUM_STATEFUL_DOMAINS="https://frontend.localhost:3000,https://backend.localhost"
SESSION_DOMAIN=".localhost"
SESSION_SECURE_COOKIE=true
SPA_URL="https://frontend.localhost:3000"

SESSION_DOMAIN应该是您的SPA应用程序和后端之间共享的域名。它应该以句点开始。

SPA_URL是您的SPA应用程序的URL。

注意

SPA功能仍在开发中，可能会有所变化。

本节文档将在功能最终确定后更新。

测试

注意

尚未为该包编写测试。它们在我的待办事项列表中。我也欢迎PR。

composer test

变更日志

有关最近变更的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞。

致谢

• Chris Reed
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。