cerbos / cerbos-sdk-php
PHP SDK for interacting with the Cerbos PDP
Requires
- php: ^8.2 || ^8.3
- ext-grpc: *
- ext-json: *
- google/common-protos: ^4.5
- google/protobuf: ^v4.26
- grpc/grpc: ^1.57
- ramsey/uuid: ^4.7
Requires (Dev)
- php-parallel-lint/php-parallel-lint: ^v1.3
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.5
- vimeo/psalm: ^5.19
This package is auto-updated.
Last update: 2024-11-11 17:26:37 UTC
README
PHP client library for the Cerbos open source access control solution. This library includes gRPC client for accessing the Cerbos PDP.
Find out more about Cerbos at https://cerbos.dev and read the documentation at https://docs.cerbos.dev.
Installation
You can install the SDK via Composer. Run the following command:
composer require cerbos/cerbos-sdk-php
Examples
Creating a gRPC client
$client = CerbosClientBuilder::newInstance($this->host) ->withPlaintext(true) ->build();
Check a single principal and resource
$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 // ... }
Check a single principal and multiple resource & action pairs
$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 // ... }
Plan Resources 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 { // ... }
Upgrading from v0.1.x
Newer versions of the library make use of gRPC libraries. This is in order to make the integration with Cerbos easier to manage. This change requires existing users of 0.1.x versions to perform some migration steps.
gRPC
This library requires the gRPC
extension to be installed. Follow the instructions for your environment to install the extension.
Differences between SDK API v0.1.x
PHP version requirements
The minimum supported version of PHP is 8.2
.
Simpler CerbosClientBuilder
CerbosClientBuilder
is simpler and only expects hostname
as a parameter.
$client = CerbosClientBuilder::newInstance("localhost:3593") ->withPlaintext(true) ->build();
Renamed ResourceAction
to ResourceEntry
The ResourceAction
class has been renamed to ResourceEntry
.
New AttributeValue
builder class
Principal and resource attributes must be created using the AttributeValue
builder class.
Creating a bool value;
$val = AttributeValue::boolValue(true);
Creating a string value;
$val = AttributeValue::stringValue("marketing");
New CheckResourcesRequest
and PlanResourcesRequest
builder classes
Use the new builder classes to construct CheckResources
and PlanResources
requests.
$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")) );
Simpler CerbosClient
The checkResources
and planResources
methods on the CerbosClient
now accepts only a CheckResourcesRequest
or
PlanResourcesRequest
object respectively.