README

这个 Keycloak 库不会从数据库中加载用户。Keycloak 用户的 UUID 通常存储在子声明中。

安装

composer require wg-hyve/keycloak-laravel-guard

配置

将您的 Keycloak 添加到守卫中，并在路由中使用它作为中间件。这就是常规使用的全部内容。

config/auth.php

return [
    'guards' => [
        // ...
        'cloak' => [
            'driver' => 'keycloak',
            'provider' => 'users',
        ],
        // ...
    ],
];

routes/api.php

Route::any('/acme', [AcmeController::class, 'index'])->middleware(['auth:cloak']);

扩展使用

KeycloakGuard 提供了一些方法来简化使用。

请求中的示例使用

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Facades\Auth;

class DeleteRequest extends FormRequest
{
    public function authorize(): bool
    {
        return Auth::hasScope('can-delete');
    }

    public function rules(): array
    {
        return [];
    }
}

其他方法

getTokenFromRequest

获取请求中的原始 Token

token(): ?stdClass

获取请求中的编码 Token

hasRole(array|string $roles): bool

证明角色或其中一个角色是否在您的客户端或全局角色中

scopes(): array

提供所有作用域

hasScope(string|array $scope): bool

证明作用域或其中一个作用域是否在您的 JWT 中

getRoles(): array

提供来自您的客户端的所有角色。客户端在 azp 声明中提供。

roles(bool $useGlobal = true): array

提供所有角色（全局和客户端）

用户

默认情况下，禁用了在本地数据库中保存用户。执行以下步骤以启用它。请确保您已阅读 .env 中环境变量的说明。

配置

在您的环境中启用 KEYCLOAK_PROVIDE_LOCAL_USER。

KEYCLOAK_PROVIDE_LOCAL_USER = true

守卫将保存 JWT 中的用户对象。

迁移

发布并执行迁移。

php artisan vendor:publish --tag=keycloak-migrations

进行调整并迁移。

php artisan migrate

用户模型

在 config/auth.php 中更新您的用户模型。您也可以扩展它并添加自己的用户模型。

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => \KeycloakGuard\Models\User::class,
    ],
],

您可以使用自己的用户模型来扩展和定义自定义关系。请确保它与上面的迁移兼容。

使用

使用 user() 获取 User 实例

namespace App\Your\Service

use Illuminate\Support\Facades\Auth;
use KeycloakGuard\Models\User;

class AcmeService
{
    public static function getUser(): ?User
    {
        return Auth::user();
    }
}

环境变量

KEYCLOAK_REALM_PUBLIC_KEY

您的 Keycloak 实例的本地公钥。您可以在 https://your-keycloak.dev.com/auth/realms/your_realm/ 中找到它

KEYCLOAK_TOKEN_PRINCIPAL_ATTRIBUTE

根据您的 Keycloak 配置，应为 azp 或 client_id

KEYCLOAK_IGNORE_RESOURCE_VALIDATION

true 或 false，自动检查使用 KEYCLOAK_ALLOWED_RESOURCES 给定的角色是否在您的令牌中

KEYCLOAK_ALLOWED_RESOURCES

要自动检查的角色

KEYCLOAK_REALM_ADDRESS

加载公钥的 URL。通常为 https://your-keycloak.dev.com/auth/realms/your_realm/

KEYCLOAK_KEY_CACHE_SECONDS

您的领域下载的公钥的缓存持续时间。

KEYCLOAK_LEEWAY

如果您收到 Cannot handle token prior to (time) error，则希望设置时间偏移（以秒为单位）。如果您的应用程序和 Keycloak 时间不同，请使用此功能。

KEYCLOAK_PROVIDE_LOCAL_USER

启用本地用户处理。守卫将尝试在本地数据库中存储用户。默认为 false。

KEYCLOAK_USER_ID_CLAIM

您的 JWT 中的用户 UUID。默认为 sub 声明。

KEYCLOAK_USER_MAIL_CLAIM

您的 JWT 中的电子邮件声明。默认为 email。

KEYCLOAK_USER_FIRSTNAME_CLAIM

您的 JWT 中的姓名声明。默认为 given_name。

KEYCLOAK_USER_LASTNAME_CLAIM

您的 JWT 中的姓氏声明。默认为 family_name。

测试

命令

# run tests with testdox
composer test

# run tests with coverage
composer test:coverage

Docker

在扩展到库后，在 Docker 中进行测试，并使用覆盖率。请不要在本地上安装 xdebug 🐌

创建一个新的源 JSON 文件

源文件存储在 tests/Data 中。生成的令牌存储在 tests/Data/tokens 中。

composer jwt:generate jwt.json access_token
composer jwt:generate jwt_realm_access.json access_token_realm_access
composer jwt:generate jwt.json access_token_has_expire true