README

概述

此包允许Laravel应用程序使用来自OpenID Connect (OIDC) 提供商的JWT令牌进行用户身份验证。它与Laravel内置的身份验证系统无缝集成，并通过允许根据每个保护器定制配置，为多租户架构提供灵活性。

安装

通过Composer安装包

composer require devadamlar/laravel-oidc

发布配置文件

php artisan vendor:publish --provider="DevAdamlar\LaravelOidc\LaravelOidcServiceProvider

用法

您首先在config/auth.php文件中定义一个保护器。

'guards' => [
    'api' => [
        'driver' => 'oidc',
        'provider' => 'users',
        'issuer' => 'https://your-auth-server.com', // must contain /.well-known/openid-configuration
    ],
],

请注意，该保护器包括issuer URL，这是您的OIDC提供商的基本URL。此URL用于获取包含公钥的发现文档。包将缓存发现文档中的公钥，确保在每次验证令牌时不会向OIDC提供商重复发送请求。

或者，您可以直接在配置文件中提供公钥，避免获取发现文档。

'guards' => [
    'api' => [
        'driver' => 'oidc',
        'provider' => 'users',
        'public_key' => 'your-public-key', // or '/path/to/public-key.pem'
        'key_disk' => 'private-s3', // optional
    ],
],

公钥存储磁盘设置为filesystems配置文件中定义的默认磁盘，但可以在保护器配置中设置key_disk或在环境变量OIDC_KEY_DISK中更改。

当为保护器设置了发行者URL和公钥时，包优先使用公钥来验证令牌。但是，如果存在发行者URL，它永远不会回退到发行者URL。

认证请求

您可以使用具有定义好的保护器的auth中间件来保护您的路由。例如，以下路由如果通过api保护器进行认证，将返回认证的用户

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return auth()->user(); // User model
});

模型检索

在提供者中定义的模型必须实现Illuminate\Contracts\Auth\Authenticatable，因为默认的User模型就是这样。它必须包含令牌中的sub声明作为身份验证标识符。默认情况下，身份验证标识符的属性是模型的主键，但您可以通过在模型中重写getAuthIdentifierName方法来更改它。

use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    public function getAuthIdentifierName()
    {
        return 'auth_uuid';
    }
}

全局配置

您可以在.env文件中设置全局配置，以适用于整个应用程序。例如，您可以在.env文件中设置发行者URL和公钥，如下所示

OIDC_ISSUER=https://your-auth-server.com
OIDC_PUBLIC_KEY=/path/to/public-key.pem

这样，您可以避免在每个保护器中重复相同的配置：对于保护器中缺少的每个配置，包将回退到全局配置。

对于发行者URL，您也可以在全局配置中设置共享的基本URL。然后，保护器级别的配置可以扩展此基本URL以添加额外的路径段。例如，您可以在全局配置中设置基本URL，如下所示

OIDC_ISSUER=https://your-auth-server.com

然后，在保护器级别的配置中扩展它，如下所示

'guards' => [
    'api' => [
        'driver' => 'oidc',
        'provider' => 'users',
        'issuer' => 'tenant1',
    ],
],

在这种情况下，api保护器的发行者URL将是https://your-auth-server.com/tenant1。

如果保护器级别的发行者配置是完整URL，它将覆盖基本URL。例如，以下配置

'guards' => [
    'api' => [
        'driver' => 'oidc',
        'provider' => 'users',
        'issuer' => 'https://tenant1-auth-server.com',
    ],
],

将忽略全局配置中设置的内容，并使用https://tenant1-auth-server.com作为发行者URL。

您可以将配置文件发布出来，并参考其中的文档以了解所有可用选项

php artisan vendor:publish --provider="DevAdamlar\LaravelOidc\LaravelOidcServiceProvider

发布文件中的每个配置选项也作为保护器级别的配置可用。

内省

自省是一种通过将令牌发送到授权服务器来验证令牌有效性的过程。这是本地验证的一种替代方案，其中服务器实时检查令牌签名和声明。

自省的好处

撤销检查：自省可以检查令牌是否已被撤销，这是本地验证无法做到的。
不透明令牌：它允许验证不透明令牌，这些令牌由于不包含所需信息而无法在本地验证。
动态信息：自省可以提供有关令牌的实时信息，确保验证是最新的。

自省的基本设置

要启用自省，请在您的 .env 文件中配置以下内容

OIDC_USE_INTROSPECTION=true
OIDC_INTROSPECTION_AUTH_METHOD=client_secret_basic
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

对于守护程序级别的配置，设置以下内容

'guards' => [
    'api' => [
        'driver' => 'oidc',
        'provider' => 'users',
        'issuer' => 'https://your-auth-server.com',
        'use_introspection' => true,
        'introspection_auth_method' => 'client_secret_basic', // [, 'client_secret_post', 'client_secret_jwt', 'private_key_jwt']
        'client_id' => 'your-client-id',
        'client_secret' => 'your-client-secret',
    ],
    // Other guards...
],

缓存

该软件包将从中获取的公钥缓存到发现文档中，以避免对 OIDC 提供商的重复请求。默认情况下，对于 production 环境，缓存持续时间设置为 24 小时，但可以在配置文件或 .env 文件中更改。

OIDC_CACHE_TTL=1440

OPs 通常不会频繁更改其公钥，但如果发生这种情况，您可以清除缓存以获取新的密钥。

php artisan cache:forget https://your-issuer-url.com
php artisan cache:forget https://your-issuer-url.com:jwks

待办事项

放置覆盖率、构建、安全性和可维护性徽章
整合 git 钩子
使用 GitHub Actions 实现持续集成/持续部署 (CI/CD) 管道
添加贡献指南
将应用程序容器化
添加清除缓存的命令
添加令牌验证检查的钩子
添加公钥更改时清除缓存的钩子

devadamlar / laravel-oidc

维护者

详细信息