README

介绍

此库提供了一款PHP编写的客户端，用于用户认证和许可证管理，兼容许多PHP API资源服务器。

安装

需求

以下步骤解释了以下包的安装：

PHP 8或更高版本
composer

使用composer安装

如果您的项目使用composer，只需添加以下内容。

composer require pebble-solutions/pebbleauthclient

使用方法

配置

在您可以使用此库之前，您必须定义一个系统环境变量，其中包含公共Json Web Key Set (远程JWKS文件)的URI。

此文件将被请求并临时存储在您的API服务器上。您的服务器应能够写入./var/credentials/auth/jwks.json。如果文件不存在，它将被创建。

如果您直接从终端启动服务器，请在启动服务器之前在终端上运行此命令

export PBL_JWKS_REMOTE_URI=https://SERVER_URI/path/jwks.json

如果您在Docker容器中启动服务器，您应该在Dockerfile中添加此行

ENV PBL_JWKS_REMOTE_URI=https://SERVER_URI/path/jwks.json

其他配置

您可以通过在系统上定义一些额外的环境变量来添加更多配置。这些配置具有默认值，适用于大多数情况。

测试密钥对

警告

这些密钥文件未加密，并且仅应在本地开发环境中用于测试目的！

JWKS URI（对于PBL_JWKS_REMOTE_URI环境变量）

https://storage.googleapis.com/pebble-public-cdn/test_auth/jwks_test.json

用于签名令牌的公钥和私钥

https://storage.googleapis.com/pebble-public-cdn/test_auth/public_test.pem

https://storage.googleapis.com/pebble-public-cdn/test_auth/private_test.pem

使用令牌字符串进行认证

$authService = new \PebbleAuthClient\Services\auth();

try {
    $pebbleAuthToken = $authService->auth("a.valid.token");
    $user = $pebbleAuthToken->getUser();
    $licence = $pebbleAuthToken->getAuthenticatedLicence();

    var_dump($pebbleAuthToken);
    var_dump($user);
    var_dump($licence);
}
catch (Exception $e) {
    echo "Error : ".$e->getMessage();
}

使用HTTP授权头进行认证

注意

此示例显示了在服务器端使用授权头验证用户的一种方法。重要的是将一个包含有效授权键值的数组传递给authFromHttpHeaders()函数。

/**
 * This class is an example of a custom authenticator for symfony.
 */
class TokenAuthenticator extends AbstractAuthenticator
{
    /** ... */

    public function authenticate(Request $request): Passport
    {
        $authService = new \PebbleAuthClient\Services\auth();

        try {
            $pebbleAuthToken = $authService->authFromHttpHeaders($request->headers->all());
            $user = $pebbleAuthToken->getUser();
            $licence = $pebbleAuthToken->getAuthenticatedLicence();

            var_dump($pebbleAuthToken);
            var_dump($user);
            var_dump($licence);
        }
        catch (Exception $e) {
            throw $e;
        }

        // implement your own logic to get the user identifier
        $userIdentifier = /** ... */;

        return new SelfValidatingPassport(new UserBadge($userIdentifier));
    }

    /** ... */
}

注意

authFromHttpHeaders()方法中的$headers参数符合PSR-7标准建议。这些值必须被视为有效。

键与字符串的关系

[
    "authorization" => "my.valid.token"
]

键与字符串数组的关联

[
    "authorization" => [
        "my.valid.token"
    ]
]

然而，即使PSR-7接受同一标题名称的多个值，以下也会导致AmbiguousToken错误。不允许通过授权头提供多个令牌。

[
    "authorization" => [
        "my.first.token",
        "my.second.token"
    ]
]

检查受众

受众标识了令牌旨在发送给哪些接收者。每个资源服务器必须通过其受众名称进行标识，并且授权过程必须检查此受众是否存在于令牌中。

警告

默认情况下，授权过程不会检查受众。资源服务器有责任传达其受众名称，以便仅接受为特定资源服务器生成的令牌。

要检查受众，请将一个$options数组添加到auth()或authFromHttpHeaders()函数中。

$authService = new \PebbleAuthClient\Services\auth();

// Check that the provided token has a valid audience for api.pebble.solutions/v5/my-resource
$auth_token = $authService->auth("----my.valid.token----", [
    'audience' => "api.pebble.solutions/v5/my-resource"
]);

// Check that token communicate through authorization header has a valid audience
// for api.pebble.solutions/v5/my-resource
$auth_token = $authService->authFromHttpHeaders(headers, [
    'audience' => "api.pebble.solutions/v5/my-resource"
]);

pebble-solutions / pebbleauthclient

维护者

详细信息