README

PHP 客户端库，用于与 Cerbos 开源访问控制解决方案（Cerbos）交互。此库包含用于访问 Cerbos PDP 的 gRPC 客户端。

了解更多关于 Cerbos 的信息，请访问 https://cerbos.dev 并阅读文档 https://docs.cerbos.dev。

安装

您可以通过 Composer 安装 SDK。运行以下命令

composer require cerbos/cerbos-sdk-php

示例

创建 gRPC 客户端

$client = CerbosClientBuilder::newInstance($this->host)
    ->withPlaintext(true)
    ->build();

检查单个主体和资源

$request = CheckResourcesRequest::newInstance()
    ->withRequestId(RequestId::generate())
    ->withPrincipal(
        Principal::newInstance("john")
            ->withRole("employee")
            ->withPolicyVersion("20210210")
            ->withAttribute("department", AttributeValue::stringValue("marketing"))
            ->withAttribute("geography", AttributeValue::stringValue("GB"))
    )
    ->withResourceEntry(
        ResourceEntry::newInstance("leave_request", "xx125")
            ->withActions(["view:public", "approve"])
            ->withPolicyVersion("20210210")
            ->withAttribute("department", AttributeValue::stringValue("marketing"))
            ->withAttribute("geography", AttributeValue::stringValue("GB"))
            ->withAttribute("owner", AttributeValue::stringValue("john"))
    )
  
$checkResourcesResponse = $client->checkResources($request);
$resultEntry = $checkResourcesResponse->find("xx125");

if ($resultEntry->isAllowed("view:public")) { // returns true if `view:public` action is allowed
    // ...
}

if ($resultEntry->isAllowed("approve")) { // returns true if `approve` action is allowed
    // ...
}

检查单个主体和多个资源 & 动作对

$request = CheckResourcesRequest::newInstance()
    ->withRequestId(RequestId::generate())
    ->withPrincipal(
        Principal::newInstance("john")
            ->withRole("employee")
            ->withPolicyVersion("20210210")
            ->withAttribute("department", "marketing")
            ->withAttribute("geography", "GB")
    )
    ->withResourceEntries(
        array(
            ResourceEntry::newInstance("leave_request", "xx125")
                ->withAction("approve")
                ->withPolicyVersion("20210210")
                ->withAttribute("department", AttributeValue::stringValue("marketing"))
                ->withAttribute("geography", AttributeValue::stringValue("GB"))
                ->withAttribute("owner", AttributeValue::stringValue("john")),

            ResourceEntry::newInstance("leave_request", "xx225")
                ->withAction("defer")
                ->withPolicyVersion("20210210")
                ->withAttribute("department", AttributeValue::stringValue("marketing"))
                ->withAttribute("owner", AttributeValue::stringValue("john"))
        )
    )
                    
$checkResourcesResponse = $client->checkResources($request);

$resultEntry = $checkResourcesResponse->find("xx125");
if ($resultEntry->isAllowed("approve")) { // returns true if `approve` action is allowed
    // ...
}

$resultEntry = $checkResourcesResponse->find("xx225");
if ($resultEntry->isAllowed("defer")) { // returns true if `defer` action is allowed
    // ...
}

计划资源 API

$request = PlanResourcesRequest::newInstance()
    ->withRequestId(RequestId::generate())
    ->withAction("approve")
    ->withPrincipal(
        Principal::newInstance("maggie")
            ->withRole("manager")
            ->withAttribute("department", AttributeValue::stringValue("marketing"))
            ->withAttribute("geography", AttributeValue::stringValue("GB"))
            ->withAttribute("team", AttributeValue::stringValue("design"))
    )
    ->withResource(
        Resource::newInstance("leave_request", "xx125")
            ->withPolicyVersion("20210210")
    );                

$planResourcesResponse = $this->client->planResources($request);
if ($planResourcesResponse->isAlwaysAllowed()) {
    // ...
}
else if ($planResourcesResponse->isAlwaysDenied()) {
    // ...
}
else {
    // ...
}

从 v0.1.x 升级

库的新版本使用了 gRPC 库。这是为了使与 Cerbos 的集成更容易管理。此更改要求现有 0.1.x 版本的用户执行一些迁移步骤。

gRPC

此库需要安装 gRPC 扩展。根据您的环境，遵循 说明 安装扩展。

SDK API v0.1.x 的区别

PHP 版本要求

最低支持的 PHP 版本是 8.2。

更简单的 CerbosClientBuilder

CerbosClientBuilder 更简单，只期望 hostname 作为参数。

$client = CerbosClientBuilder::newInstance("localhost:3593")
    ->withPlaintext(true)
    ->build();

将 ResourceAction 重命名为 ResourceEntry

已将 ResourceAction 类重命名为 ResourceEntry。

新的 AttributeValue 构建器类

必须使用 AttributeValue 构建器类创建主体和资源属性。

创建布尔值；

$val = AttributeValue::boolValue(true);

创建字符串值；

$val = AttributeValue::stringValue("marketing");

新的 CheckResourcesRequest 和 PlanResourcesRequest 构建器类

使用新的构建器类来构建 CheckResources 和 PlanResources 请求。

$request = CheckResourcesRequest::newInstance()
    ->withRequestId(RequestId::generate())
    ->withPrincipal(
        Principal::newInstance("john")
            ->withRole("employee")
            ->withPolicyVersion("20210210")
            ->withAttribute("department", "marketing")
    )
    ->withResourceEntries(
        array(
            ResourceEntry::newInstance("leave_request", "xx125")
                ->withAction("approve")
                ->withAttribute("department", AttributeValue::stringValue("marketing")),

            ResourceEntry::newInstance("leave_request", "xx225")
                ->withAction("defer")
                ->withAttribute("department", AttributeValue::stringValue("marketing"))
        )
    );

$request = PlanResourcesRequest::newInstance()
    ->withRequestId(RequestId::generate())
    ->withAction("approve")
    ->withPrincipal(
        Principal::newInstance("maggie")
            ->withRole("manager")
            ->withAttribute("department", AttributeValue::stringValue("marketing"))
    )
    ->withResource(
        Resource::newInstance("leave_request", "xx125")
            ->withAttribute("department", AttributeValue::stringValue("marketing"))
    );

更简单的 CerbosClient

CerbosClient 上的 checkResources 和 planResources 方法现在只接受 CheckResourcesRequest 或 PlanResourcesRequest 对象。