Cerbos .NET SDK

.NET client library for the Cerbos open source access control solution. This library includes gRPC clients for accessing the Cerbos PDP.

Find out more about Cerbos at https://cerbos.dev and read the documentation at https://docs.cerbos.dev.

Installation

• Add Cerbos.Sdk NuGet package as dependency to the project. See here for the published packages.

Examples

Creating a client without TLS

var client = CerbosClientBuilder.ForTarget("http://localhost:3593").WithPlaintext().Build();

CheckResources API

var request = CheckResourcesRequest.NewInstance()
    .WithRequestId(RequestId.Generate())
    .WithIncludeMeta(true)
    .WithPrincipal(
        Principal.NewInstance("john", "employee")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
    )
    .WithResourceEntries(
        ResourceEntry.NewInstance("leave_request", "XX125")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
            .WithAttribute("owner", AttributeValue.StringValue("john"))
            .WithActions("approve", "view:public")
    );

var result = client.CheckResources(request).Find("XX125");
if(result.IsAllowed("approve")){ // returns true if `approve` action is allowed
    // ...
}

var request = CheckResourcesRequest.NewInstance()
    .WithRequestId(RequestId.Generate())
    .WithIncludeMeta(true)
    .WithPrincipal
    (
        Principal.NewInstance("john", "employee")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
    )
    .WithResourceEntries
    (
        ResourceEntry.NewInstance("leave_request", "XX125")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
            .WithAttribute("owner", AttributeValue.StringValue("john"))
            .WithActions("view:public", "approve", "defer"),
        
        ResourceEntry.NewInstance("leave_request", "XX225")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
            .WithAttribute("owner", AttributeValue.StringValue("martha"))
            .WithActions("view:public", "approve"),
        
        ResourceEntry.NewInstance("leave_request", "XX325")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("US"))
            .WithAttribute("owner", AttributeValue.StringValue("peggy"))
            .WithActions("view:public", "approve")
    );

CheckResourcesResponse result = client.CheckResources(request);
var resultXX125 = result.Find("XX125");
var resultXX225 = result.Find("XX225");
var resultXX325 = result.Find("XX325");

if(resultXX125.IsAllowed("defer")){ // returns true if `defer` action is allowed
    // ...
}

if(resultXX225.IsAllowed("approve")){ // returns true if `approve` action is allowed
    // ...
}

if(resultXX325.IsAllowed("view:public")){ // returns true if `view:public` action is allowed
    // ...
}

Plan Resources API

var request = PlanResourcesRequest.NewInstance()
    .WithRequestId(RequestId.Generate())
    .WithIncludeMeta(true)
    .WithPrincipal
    (
        Principal.NewInstance("maggie","manager")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
            .WithAttribute("geography", AttributeValue.StringValue("GB"))
            .WithAttribute("team", AttributeValue.StringValue("design"))
    )
    .WithResource
    (
        Resource.NewInstance("leave_request")
            .WithPolicyVersion("20210210")
    )
    .WithAction("approve");

PlanResourcesResponse result = client.PlanResources(request);
if(result.IsAlwaysAllowed()) {
    // ...
}
else if (result.IsAlwaysDenied()) {
    // ...
}
else {
    // ...
}

Upgrading from v0.2.x

v1.0.0 of the SDK contains some breaking API changes and requires existing users to make a few changes to their code.

CerbosBlockingClient has been renamed to CerbosClient

CerbosBlockingClient has been renamed to CerbosClient and it has support for async operations with the new CheckResourcesAsync and PlanResourcesAsync methods.

Simpler CerbosClientBuilder

CerbosClientBuilder has a static constructor and hostname is the only required parameter.

var client = CerbosClientBuilder
    .ForTarget("http://localhost:3593")
    .WithPlaintext()
    .Build();

Rename ResourceAction to ResourceEntry

Replace references to ResourceAction with ResourceEntry.

New CheckResourcesRequest and PlanResourcesRequest builder classes

The CheckResources and PlanResources methods now require a CheckResourcesRequest or a PlanResourcesRequest object respectively. They can be built using the new builder classes to construct CheckResources and PlanResources requests.

var request = CheckResourcesRequest
    .NewInstance()
    .WithRequestId(RequestId.Generate())
    .WithPrincipal(
        Principal.NewInstance("john", "employee")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
    )
    .WithResourceEntries(
        ResourceEntry.NewInstance("leave_request", "XX125")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
    );

var request = PlanResourcesRequest
    .NewInstance()
    .WithRequestId(RequestId.Generate())
    .WithPrincipal(
        Principal.NewInstance("john", "employee")
            .WithPolicyVersion("20210210")
            .WithAttribute("department", AttributeValue.StringValue("marketing"))
    )
    .WithResource
    (
        Resource.NewInstance("leave_request")
            .WithPolicyVersion("20210210")
    )
    .WithAction("approve");