cerbos/cerbos-sdk-php

PHP SDK for interacting with the Cerbos PDP

v1.2.0 2024-01-02 10:27 UTC

Requires

• php: ^8.2 || ^8.3
• ext-grpc: *
• ext-json: *
• google/common-protos: ^4.1
• google/protobuf: ^3.23
• grpc/grpc: ^1.52
• ramsey/uuid: ^4.3

Requires (Dev)

• php-parallel-lint/php-parallel-lint: ^v1.3
• phpstan/phpstan: ^1.9
• phpunit/phpunit: ^10.0
• vimeo/psalm: ^5.0

Apache-2.0

• Cerbos

• cerbos
• pdp

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.