README

请注意，此包尚不稳定，API可能会更改

此包用于简化与Clearlink SSO的认证以及通过Clearlink权限微服务的授权。

此包还将代表客户端使用OAuth2客户端凭据授权类型检索令牌。

安装

以下说明假设您已经将Clearlink的composer仓库添加到项目的composer.json文件中。

首先，需要此包

composer require clearlink/auth

这将还需要以下包

clearlink/dto
clearlink/permissions
clearlink/users

在项目中的 .env 文件中，添加以下行，将 {{client_id}}、{{client_secret}}、{{sso_url}} 和 {{users_url}} 替换为您应用程序的相应值

CL_SSO_CLIENT_ID={{client_id}}
CL_SSO_CLIENT_SECRET={{client_secret}}
CL_SSO_URL={{sso_url}}
CL_USERS_URL={{users_url}}

将来，一旦密钥放置在公开位置，以下步骤将不再需要。

然后您需要创建一个名为 storage/app/ 中的 cl_auth_public.pem 文件。此文件的正文是SSO应用程序配置中的公钥集。

从现在起，安装方式从Laravel到Lumen略有不同。首先提供Laravel的说明，然后是Lumen的说明。

Laravel安装

将以下行添加到项目的 config\app.php 文件中的 'providers' 数组中

/*
 * Package Service Providers...
 */
Clearlink\Auth\AuthServiceProvider::class,
Clearlink\DTO\DTOServiceProvider::class

Both clearlink/auth 和 clearlink/dto 都有配置文件，但只有当您连接到UAT环境或想要使用本地定义的用户实例时，才需要发布 clearlink/auth 配置。要发布到 clearlink/dto 配置文件，请运行以下

php artisan vendor:publish --tag=clearlink-dto

该文件将被发布到 config/clearlink-dto.php，并将包含一个键为 modules 的数组。您需要取消注释 modules 中的前两个条目，以便文件看起来像以下

return [
    'modules' => [
        \Clearlink\Users\Factory::class,
        \Clearlink\Permissions\Factory::class,
        // Possible other entries...
    ]
];

这将允许 clearlink\auth 包将对象的JSON表示形式序列化为强类型对象。

有关使用UAT环境或自定义用户的配置，请参阅后续部分。

修改 app\Exceptions\Handler->unauthenticated，以便在未认证的情况下重定向到SSO

protected function unauthenticated($request, AuthenticationException $exception)
{
    if ($request->expectsJson()) {
        return response()->json(['error' => 'Unauthenticated.'], 401);
    }

    //replace this line
    //return redirect()->guest('login');
    //with this line
    return app(AuthService::class)->getAuthorizationCodeRedirect($request);
}

更新 config/auth.php 以使用提供的授权守卫和用户提供者。只需将 'clearlink-' 预先附加到 api 和 web 认证守卫的驱动程序，并将 users 提供者的驱动程序更改为 'clearlink'

'guards' => [
    'web' => [
        'driver' => 'clearlink-session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'clearlink-token',
        'provider' => 'users',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'clearlink',
    ],
],

最后，您需要将 auth 中间件添加到您想要保护的路由。请参阅Laravel文档了解如何向路由添加中间件。

现在，每当您调用 $request->user() 或 Auth::user() 时，您将获取一个 Clearlink\Auth\User 实例。

Lumen安装

打开 bootstrap/app.php 并在服务提供者部分添加以下行（大约在72行附近）

$app->register(Clearlink\DTO\DTOServiceProvider::class);
$app->register(Clearlink\Auth\AuthServiceProvider::class);

注意：在Lumen中，服务提供者的注册顺序很重要。截至Lumen 5.3，服务提供者的boot方法在register方法之后立即调用，而应该先调用所有提供者的register方法，然后调用所有提供者的boot方法。

在 bootstrap/app.php 中，取消注释添加 auth 中间件到应用程序的行（大约在68行附近）

$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);

光量（Lumen）不包含 artisan vendor:publish 命令，因此需要将 clearlink-dto.php 配置文件从供应商文件夹复制到配置文件夹

cp vendor/clearlink/dto/config/clearlink-dto.php config/

如果您计划使用自定义用户，还需要发布 clearlink-auth.php 配置文件

cp vendor/clearlink/auth/config/clearlink-auth.php config/

clearlink-dto.php 配置文件将包含一个键为 modules 的数组。您需要取消注释 modules 中的前两个条目，使文件看起来如下

return [
    'modules' => [
        \Clearlink\Users\Factory::class,
        \Clearlink\Permissions\Factory::class,
        // Possible other entries...
    ]
];

这将允许 clearlink\auth 包将对象的JSON表示形式序列化为强类型对象。

接下来需要做的就是将 auth 中间件添加到您想要保护的路由中。请参阅 Laravel 文档了解如何向路由添加中间件。

附加配置

UAT 环境

注意：此内容仅适用于 Laravel 安装。

如果您连接到 UAT 环境，还需要发布 clearlink/auth 配置文件，内容如下

php artisan vendor:publish --tag=clearlink-auth

在配置中找到键 authEndpoint 并在值后添加一个尾随斜杠，使其为

'authEndpoint' => env('CL_SSO_URL') . '/v1/auth/'

注意：通常，配置文件是受源代码控制的。clearlink-auth 文件中的配置需要在 UAT 和非 UAT 环境之间有所不同。该文件中的默认配置适用于非 UAT 环境，因此可以接受将 clearlink-auth.php 配置文件添加到 .gitignore 中。

自定义用户对象

默认情况下，clearlink/auth 包返回类型为 Clearlink\Auth\User 的用户，但您可以通过覆盖包来返回您选择的任何对象。如果您选择覆盖默认对象，您希望使用的对象 必须 实现 Illuminate\Contracts\Auth\Authenticatable 接口，并具有 Clearlink\Auth\Traits\ClearlinkUser 特性。Laravel\Lumen 的默认用户实现了 Illuminate\Contracts\Auth\Authenticatable 接口，因此如果您想使用该类，只需将其添加到 User 类中即可。

<?php

namespace App;

...
use Clearlink\Auth\Traits\ClearlinkAuthUser;
use Illuminate\Foundation\Auth\User as Authenticatable;
...

class User extends Authenticatable
{
    use Notifiable, ClearlinkAuthUser;

    ...
}

要覆盖返回的用户，必须在 clearlink/auth 配置文件中指定 userRepository。该文件可以通过以下方式发布

#For Laravel:
php artisan vendor:publish --tag=clearlink-auth

#For Lumen:
cp vendor/clearlink/auth/config/clearlink-auth.php config/

指定的对象必须有一个签名符合 find($id) 的函数，其中 $id 是 DNA 用户 ID。

'userRepository' => new \App\User

如果您覆盖了默认用户，并且您指定的存储库返回 NULL，对象没有实现 Illuminate\Contracts\Auth\Authenticatable 接口，或者对象没有 Clearlink\Auth\Traits\ClearlinkUser 特性，将抛出异常。

授权后操作

在用户认证后执行代码可能很有帮助，此包提供了在用户认证后对您的项目执行函数的方法。指定的函数将在从用户微服务检索用户对象后运行，但在从 UserProvider 返回用户之前。这有助于在覆盖用户时在您的项目数据库中创建用户。

指定的函数 必须 接收一个类型为 Clearlink\Users\BaseUser 的参数。它需要是 BaseUser，因为应用程序和常规（人类）用户都可以认证到您的系统，并且它们有不同的从 BaseUser 继承的类。最常见的类将是 User（这是人类用户）而应用程序用户将是 ApplicationUser 类型。

要指定函数，请将以下内容放入您的 AppServiceProvider 的 boot 方法中，替换为您的选择函数

$this->app[\Clearlink\Auth\AuthService::class]->setAuthenticatedFunction(function (\Clearlink\Users\BaseUser $user){});

注意：如果这是一个 Lumen 安装，则必须将 AppServiceProvider 在 Clearlink/Auth/AuthServiceProvider 之后注册。

注销

注意：此内容仅适用于 Laravel 安装。

AuthService 类提供了一个函数，可以清除会话并生成一个 RedirectResponse，您可以使用它来注销 SSO。在您的应用程序的路由文件中添加类似以下内容可以成功注销用户从应用程序和 SSO

Route:get('/logout', function(Request $request) {
    return app(\Clearlink\Auth\AuthService::class)->getLogoutRedirect($request);
});

注意：当前SSO存在一个bug，导致使用clearlink/auth包的应用程序无法从注销页面重新登录。相反，您的用户需要先注销，然后导航回应用程序的根URL，系统会将其重定向到SSO登录页面。