Package: cerbos
Cerbos Python SDKPython clients for accessingCerbos.Cerbos is the open core, language-agnostic, scalable authorization solution that makes user permissions and authorization simple to implement and manage by writing context-aware access control policies for your application resources.UsageThis library is available from PyPI ascerbos. It supports both async and non-async modes.pipinstallcerbosThere are two clients available;gRPCandHTTP. New projects should use the gRPC client.gRPC Client(Available from v0.8.0 onwards)Making a requestfromcerbos.sdk.grpc.clientimportCerbosClientfromcerbos.engine.v1importengine_pb2fromcerbos.request.v1importrequest_pb2fromgoogle.protobuf.struct_pb2importValueprincipal=engine_pb2.Principal(id="john",roles={"employee"},policy_version="20210210",attr={"department":Value(string_value="marketing"),"geography":Value(string_value="GB"),"team":Value(string_value="design"),},)resource=engine_pb2.Resource(id="XX125",kind="leave_request",attr={"id":Value(string_value="XX125"),"department":Value(string_value="marketing"),"geography":Value(string_value="GB"),"team":Value(string_value="design"),"owner":Value(string_value="john"),})plan_resource=engine_pb2.PlanResourcesInput.Resource(kind="leave_request",policy_version="20210210")withCerbosClient("localhost:3593",tls_verify=False)asc:# Check a single action on a single resourceifc.is_allowed("view",principal,resource):# perform some actionpass# Get the query plan for "view" actionplan=c.plan_resources(action="view",principal=principal,resource=plan_resource)Async usagefromcerbos.sdk.grpc.clientimportAsyncCerbosClientasyncwithAsyncCerbosClient("localhost:3593",tls_verify=False)asc:...allowed=awaitc.is_allowed("view:public",p,r)print(allowed)# Get the query plan for "view" action...plan=awaitc.plan_resources("view",p,rd)print(plan.filter.to_json())Admin APIThere is also a client available for interacting with the Admin API. Seethe docsfor information on how to configure your PDP to enable this.fromcerbos.policy.v1importpolicy_pb2fromcerbos.sdk.grpc.clientimportAdminCredentials,AsyncCerbosAdminClientadmin_credentials=AdminCredentials(username="admin",password="some_password")asyncwithAsyncCerbosAdminClient("localhost:3593",admin_credentials=admin_credentials)asc:awaitc.add_or_update_policy([policy_pb2.Policy(api_version="api.cerbos.dev/v1",principal_policy=policy_pb2.PrincipalPolicy(principal="terry",version="default"),)])Connecting to a Unix domain socketwithCerbosClient("unix:/var/cerbos.sock",tls_verify=False)asc:...Enabling TLStls_verifycan either be the certificate location (string) or a boolean. IfTrue, it'll look for the file at the location specified by the environment variableSSL_CERT_FILE, else the default OS location.withCerbosClient("localhost:3593",tls_verify=True)asc:...withCerbosClient("localhost:3593",tls_verify="path/to/tls.crt")asc:...Optional channel argumentsYou can pass additional options in thechannel_optionsdict.
Available options are describedhere.
The argument is of typedict[str, Any]where theAnyvalue must match the expected type defined in the previous link.NOTE: We provide this as a generic method to set arbitrary options for particular use cases.
For purely demonstrative purposes, our example below overridesgrpc.ssl_target_name_override, which is certainly not recommended practice for production applications.opts={"grpc.ssl_target_name_override":"localhost"}withCerbosClient("localhost:3593",tls_verify=True,channel_options=opts)asc:...HTTP clientWe maintain this for backwards compatibility. It is recommended to use thegRPC client.Making a requestfromcerbos.sdk.modelimport*fromcerbos.sdk.clientimportCerbosClientwithCerbosClient("https://localhost:3592",debug=True,tls_verify=False)asc:p=Principal("john",roles={"employee"},policy_version="20210210",attr={"department":"marketing","geography":"GB","team":"design"},)# Check a single action on a single resourcer=Resource("XX125","leave_request",policy_version="20210210",attr={"id":"XX125","department":"marketing","geography":"GB","team":"design","owner":"john",},)allowed=c.is_allowed("view:public",p,r)print(allowed)# Get the query plan for "view" actionrd=ResourceDesc("leave_request",policy_version="20210210")plan=c.plan_resources("view",p,rd)print(plan.filter.to_json())Async usagefromcerbos.sdk.modelimport*fromcerbos.sdk.clientimportAsyncCerbosClientasyncwithAsyncCerbosClient("https://localhost:3592",debug=True,tls_verify=False)asc:...# Check a single action on a single resource...allowed=awaitc.is_allowed("view:public",p,r)print(allowed)# Get the query plan for "view" action...plan=awaitc.plan_resources("view",p,rd)print(plan.filter.to_json())Connecting to a Unix domain socketUseunix+http:///path/to/sockfor HTTP over UDS orunix+https:///path/to/sockfor HTTPS over UDS.withCerbosClient("unix+https:///var/cerbos.sock",debug=True,tls_verify=False)asc:...Testing withTestContainersNOTE: Requirescerbos[testcontainers]dependency to be installed.fromcerbos.sdk.clientimportCerbosClientfromcerbos.sdk.containerimportCerbosContainercontainer=CerbosContainer()policy_dir=os.path.join(os.path.dirname(os.path.abspath(__file__)),"store")container.with_volume_mapping(policy_dir,"/policies")withcontainer:container.wait_until_ready()host=container.http_host()withCerbosClient(host)asc:...See the tests available in thetestsdirectory for more examples.ContributingThe gRPC client uses protoc generated python classes from definitions retrieved from ourbuf registry.
When making changes to this library, be sure to run the./proto/generate_protos.shto update definitions and generate python classes.Get helpVisit theCerbos websiteRead thedocumentationJoin the Cerbos community on SlackEmail us athelp@cerbos.dev