https://github.com/cerbos/cerbos-sdk-net

.NET SDK for interacting with the Cerbos PDP
https://github.com/cerbos/cerbos-sdk-net

Last synced: about 2 months ago
JSON representation

.NET SDK for interacting with the Cerbos PDP

• Host: GitHub
• URL: https://github.com/cerbos/cerbos-sdk-net
• Owner: cerbos
• License: apache-2.0
• Created: 2022-05-11T18:13:44.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-11-06T09:55:18.000Z (about 2 months ago)
• Last Synced: 2024-11-06T10:54:38.323Z (about 2 months ago)
• Language: C#
• Homepage:
• Size: 1.5 MB
• Stars: 14
• Watchers: 4
• Forks: 3
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
[![NuGeT](https://img.shields.io/nuget/v/Cerbos.Sdk?style=plastic)](https://www.nuget.org/packages/Cerbos.Sdk)

[![NuGeT Downloads](https://img.shields.io/nuget/dt/Cerbos.Sdk?style=plastic)](https://www.nuget.org/packages/Cerbos.Sdk)

# Cerbos .NET SDK

.NET client library for the [Cerbos](https://github.com/cerbos/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](https://www.nuget.org/packages/Cerbos.Sdk) for the published packages.

# Examples

## Creating a client without TLS

```csharp

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

```

## CheckResources API

```csharp

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

    // ...

}

```

```csharp

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

```csharp

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.

```csharp

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.

```csharp

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"))

    );

```

```csharp

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");

```