Cerbos PHP SDK

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.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

chore(deps): update dependency phpunit/phpunit to v10.5.27

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

chore(deps): update dependency phpunit/phpunit to v11

Detected dependencies

composer

composer.json

php ^8.2 || ^8.3

google/common-protos ^4.5

google/protobuf ^v4.26

grpc/grpc ^1.57

ramsey/uuid ^4.7

php-parallel-lint/php-parallel-lint ^v1.3

phpstan/phpstan ^1.10

phpunit/phpunit ^10.5

vimeo/psalm ^5.19

docker-compose

docker-compose.yaml

github-actions

.github/workflows/pr-title.yaml

amannn/action-semantic-pull-request v5

.github/workflows/pr.yaml

actions/checkout v4

shivammathur/setup-php v2

bufbuild/buf-setup-action v1.34.0

actions/checkout v4

shivammathur/setup-php v2

actions/checkout v4

actions/checkout v4

shivammathur/setup-php v2

Check this box to trigger a request for Renovate to run again on this repository

cerbos / cerbos-sdk-php Goto Github PK

cerbos-sdk-php's Introduction

Cerbos PHP SDK

Installation

Examples

Creating a gRPC client

Check a single principal and resource

Check a single principal and multiple resource & action pairs

Plan Resources API

Upgrading from v0.1.x

gRPC

Differences between SDK API v0.1.x

PHP version requirements

Simpler CerbosClientBuilder

Renamed ResourceAction to ResourceEntry

New AttributeValue builder class

New CheckResourcesRequest and PlanResourcesRequest builder classes

Simpler CerbosClient

cerbos-sdk-php's People

Contributors

Stargazers

Watchers

Forkers

cerbos-sdk-php's Issues