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

Cerbos

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 {
    // ...
}

Note

Cerbos PDP v0.44.0 and onwards support specifying multiple actions with the following syntax:

->withActions(array("create", "delete"))

Cerbos Hub

Creating a gRPC client

use Cerbos\Sdk\Cloud\HubClientBuilder;

$hubClient = HubClientBuilder::fromEnv() // Gets clientId and clientSecret from environment variables CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET.
    ->build();

$storeClient = $hubClient->storeClient();

GetFiles API

use Cerbos\Sdk\Cloud\Store\V1\GetFilesRequest;

$request = GetFilesRequest::newInstance(
    $storeId,
    "resource_policies/leave_request.yaml",
    "resource_policies/purchase_order.yaml"
);

$response = $storeClient->getFiles($request);

ListFiles API

use Cerbos\Sdk\Cloud\Store\V1\FileFilter;
use Cerbos\Sdk\Cloud\Store\V1\ListFilesRequest;

$request = ListFilesRequest::newInstance($storeId);

$requestWithFilter = ListFilesRequest::withFilter(
    $storeId,
    FileFilter::pathContains(self::something)
);

$response = $storeClient->listFiles($request);
$filteredResponse = $storeClient->listFiles($requestWithFilter);

ModifyFiles API

use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails;
use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails\Internal;
use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails\Uploader;
use Cerbos\Sdk\Cloud\Store\V1\FileOp;
use Cerbos\Sdk\Cloud\Store\V1\ModifyFilesRequest;

$path = __DIR__ . "./cerbos/policies/leave_request.yaml";
$realPath = realpath($path);
$fileContents = file_get_contents($realPath);

$requestAddOrUpdate = ModifyFilesRequest::withChangeDetails(
    $storeId,
    ChangeDetails::internal(
        'myApp/ModifyFiles/Op=AddOrUpdate',
        Uploader::newInstance('myApp'),
        Internal::newInstance('sdk')
    ),
    FileOp::addOrUpdate('policies/leave_request.yaml', $fileContents)
);

$requestDelete = ModifyFilesRequest::withChangeDetails(
    $storeId,
    ChangeDetails::internal(
        'myApp/ModifyFiles/Op=Delete',
        Uploader::newInstance('myApp'),
        Internal::newInstance('sdk')
    ),
    FileOp::delete('policies/leave_request.yaml')
);

$responseAddOrUpdate = $storeClient->modifyFiles($requestAddOrUpdate);
$responseDelete = $storeClient->modifyFiles($requestDelete);

ReplaceFiles API

use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails;
use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails\Internal;
use Cerbos\Sdk\Cloud\Store\V1\ChangeDetails\Uploader;
use Cerbos\Sdk\Cloud\Store\V1\ReplaceFilesRequest;

$path = __DIR__ . "./cerbos/policies.zip";
$realPath = realpath($path);
$fileContents = file_get_contents($realPath);

$request = ReplaceFilesRequest::withZippedContents(
    $storeId,
    $fileContents,
    null,
    ChangeDetails::internal(
        'myApp/ReplaceFiles/With=policies.zip',
        Uploader::newInstance('myApp'),
        Internal::newInstance('sdk')
    )
);

$response = $storeClient->replaceFiles($request);