{"id":18715106,"url":"https://github.com/cerbos/cerbos-sdk-python","last_synced_at":"2025-04-12T13:07:58.031Z","repository":{"id":38461063,"uuid":"479472308","full_name":"cerbos/cerbos-sdk-python","owner":"cerbos","description":"Cerbos Python SDK ","archived":false,"fork":false,"pushed_at":"2025-02-20T16:46:16.000Z","size":387,"stargazers_count":16,"open_issues_count":4,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T13:07:45.332Z","etag":null,"topics":["access-control","api-client","authorization","authz","library","python","python3","security"],"latest_commit_sha":null,"homepage":"https://cerbos.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cerbos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-08T16:57:43.000Z","updated_at":"2025-04-09T10:21:15.000Z","dependencies_parsed_at":"2024-01-17T13:06:43.139Z","dependency_job_id":"6336caff-f0ef-43b1-8564-64f2b5752344","html_url":"https://github.com/cerbos/cerbos-sdk-python","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerbos","download_url":"https://codeload.github.com/cerbos/cerbos-sdk-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571893,"owners_count":21126522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","api-client","authorization","authz","library","python","python3","security"],"created_at":"2024-11-07T13:07:36.020Z","updated_at":"2025-04-12T13:07:58.003Z","avatar_url":"https://github.com/cerbos.png","language":"Python","readme":"Cerbos Python SDK\n=================\n\nPython clients for accessing [Cerbos](https://cerbos.dev).\n\nCerbos 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.\n\n## Usage\n\nThis library is available from PyPI as `cerbos`. It supports both async and non-async modes.\n\n```sh\npip install cerbos\n```\n\nThere are two clients available; [gRPC](#grpc-client) and [HTTP](#http-client). New projects should use the gRPC client.\n\n### gRPC Client\n\n(Available from v0.8.0 onwards)\n\n**Making a request**\n\n```python\nfrom cerbos.sdk.grpc.client import CerbosClient\nfrom cerbos.engine.v1 import engine_pb2\nfrom cerbos.request.v1 import request_pb2\nfrom google.protobuf.struct_pb2 import Value\n\nprincipal = engine_pb2.Principal(\n    id=\"john\",\n    roles={\"employee\"},\n    policy_version=\"20210210\",\n    attr={\n        \"department\": Value(string_value=\"marketing\"),\n        \"geography\": Value(string_value=\"GB\"),\n        \"team\": Value(string_value=\"design\"),\n    },\n)\n\nresource = engine_pb2.Resource(\n    id=\"XX125\",\n    kind=\"leave_request\",\n    attr={\n        \"id\": Value(string_value=\"XX125\"),\n        \"department\": Value(string_value=\"marketing\"),\n        \"geography\": Value(string_value=\"GB\"),\n        \"team\": Value(string_value=\"design\"),\n        \"owner\": Value(string_value=\"john\"),\n    }\n)\n\nplan_resource = engine_pb2.PlanResourcesInput.Resource(\n    kind=\"leave_request\",\n    policy_version=\"20210210\"\n)\n\nwith CerbosClient(\"localhost:3593\", tls_verify=False) as c:\n    # Check a single action on a single resource\n    if c.is_allowed(\"view\", principal, resource):\n        # perform some action\n        pass\n\n    # Get the query plan for \"view\" action\n    plan = c.plan_resources(action=\"view\", principal=principal, resource=plan_resource)\n````\n\n**Async usage**\n\n```python\nfrom cerbos.sdk.grpc.client import AsyncCerbosClient\n\nasync with AsyncCerbosClient(\"localhost:3593\", tls_verify=False) as c:\n    ...\n\n    allowed = await c.is_allowed(\"view:public\", p, r)\n    print(allowed)\n\n    # Get the query plan for \"view\" action\n    ...\n    plan = await c.plan_resources(\"view\", p, rd)\n    print(plan.filter.to_json())\n\n```\n\n**Admin API**\n\nThere is also a client available for interacting with the Admin API. See [the docs](https://docs.cerbos.dev/cerbos/latest/api/admin_api.html) for information on how to configure your PDP to enable this.\n\n```python\nfrom cerbos.policy.v1 import policy_pb2\nfrom cerbos.sdk.grpc.client import AdminCredentials, AsyncCerbosAdminClient\n\nadmin_credentials = AdminCredentials(username=\"admin\", password=\"some_password\")\nasync with AsyncCerbosAdminClient(\"localhost:3593\", admin_credentials=admin_credentials) as c:\n    await c.add_or_update_policy(\n        [\n            policy_pb2.Policy(\n                api_version=\"api.cerbos.dev/v1\",\n                principal_policy=policy_pb2.PrincipalPolicy(\n                    principal=\"terry\", version=\"default\"\n                ),\n            )\n        ]\n    )\n```\n\n**Connecting to a Unix domain socket**\n\n```python\nwith CerbosClient(\"unix:/var/cerbos.sock\", tls_verify=False) as c:\n  ...\n```\n\n**Enabling TLS**\n\n`tls_verify` can either be the certificate location (string) or a boolean. If `True`, it'll look for the file at the location specified by the environment variable `SSL_CERT_FILE`, else the default OS location.\n\n```python\nwith CerbosClient(\"localhost:3593\", tls_verify=True) as c:\n  ...\n```\n\n```python\nwith CerbosClient(\"localhost:3593\", tls_verify=\"path/to/tls.crt\") as c:\n  ...\n```\n\n**Optional channel arguments**\n\nYou can pass additional options in the `channel_options` dict.\nAvailable options are described [here](https://github.com/grpc/grpc/blob/7536d8a849c0096e4c968e7730306872bb5ec674/include/grpc/impl/grpc_types.h).\nThe argument is of type `dict[str, Any]` where the `Any` value must match the expected type defined in the previous link.\n\nIMPORTANT: We use the config key `grpc.service_config` to set service-specific configuration (retry policies, backoffs etc) within the nested JSON field. Passing this as a `channel_options` key will override that configuration entirely. We recommend leaving this untouched, however, if you need to pass custom config, ensure you pass the entire existing dict along with the desired updates (this can be found within the `AsyncClientBase.__init__` method).\n\nNOTE: We provide this as a generic method to set arbitrary options for particular use cases.\nFor purely demonstrative purposes, our example below overrides `grpc.ssl_target_name_override`, which is certainly not recommended practice for production applications.\n\n```python\nopts = {\n    \"grpc.ssl_target_name_override\": \"localhost\"\n}\nwith CerbosClient(\"localhost:3593\", tls_verify=True, channel_options=opts) as c:\n  ...\n```\n\n### HTTP client\n\nWe maintain this for backwards compatibility. It is recommended to use the [gRPC client](#grpc-client).\n\n**Making a request**\n\n```python\nfrom cerbos.sdk.model import *\nfrom cerbos.sdk.client import CerbosClient\n\nwith CerbosClient(\"https://localhost:3592\", debug=True, tls_verify=False) as c:\n    p = Principal(\n        \"john\",\n        roles={\"employee\"},\n        policy_version=\"20210210\",\n        attr={\"department\": \"marketing\", \"geography\": \"GB\", \"team\": \"design\"},\n    )\n\n    # Check a single action on a single resource\n    r = Resource(\n        \"XX125\",\n        \"leave_request\",\n        policy_version=\"20210210\",\n        attr={\n            \"id\": \"XX125\",\n            \"department\": \"marketing\",\n            \"geography\": \"GB\",\n            \"team\": \"design\",\n            \"owner\": \"john\",\n        },\n    )\n\n    allowed = c.is_allowed(\"view:public\", p, r)\n    print(allowed)\n\n    # Get the query plan for \"view\" action\n    rd = ResourceDesc(\"leave_request\", policy_version=\"20210210\")\n    plan = c.plan_resources(\"view\", p, rd)\n    print(plan.filter.to_json())\n```\n\n**Async usage**\n\n```python\nfrom cerbos.sdk.model import *\nfrom cerbos.sdk.client import AsyncCerbosClient\n\nasync with AsyncCerbosClient(\"https://localhost:3592\", debug=True, tls_verify=False) as c:\n    ...\n\n    # Check a single action on a single resource\n    ...\n    allowed = await c.is_allowed(\"view:public\", p, r)\n    print(allowed)\n\n    # Get the query plan for \"view\" action\n    ...\n    plan = await c.plan_resources(\"view\", p, rd)\n    print(plan.filter.to_json())\n\n```\n\n**Connecting to a Unix domain socket**\n\nUse `unix+http:///path/to/sock` for HTTP over UDS or `unix+https:///path/to/sock` for HTTPS over UDS.\n\n```python\nwith CerbosClient(\"unix+https:///var/cerbos.sock\", debug=True, tls_verify=False) as c:\n  ...\n```\n\n**Testing with [TestContainers](https://github.com/testcontainers/testcontainers-python)**\n\nNOTE: Requires `cerbos[testcontainers]` dependency to be installed.\n\n```python\nfrom cerbos.sdk.client import CerbosClient\nfrom cerbos.sdk.container import CerbosContainer\n\ncontainer = CerbosContainer()\npolicy_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), \"store\")\ncontainer.with_volume_mapping(policy_dir, \"/policies\")\n\nwith container:\n    container.wait_until_ready()\n\n    host = container.http_host()\n    with CerbosClient(host) as c:\n        ...\n```\n\n\nSee the tests available in the `tests` directory for more examples.\n\n## Contributing\n\nThe gRPC client uses protoc generated python classes from definitions retrieved from our [buf registry](https://buf.build/cerbos/cerbos-api).\nWhen making changes to this library, be sure to run the `./proto/generate_protos.sh` to update definitions and generate python classes.\n\n## Get help\n\n- Visit the [Cerbos website](https://cerbos.dev)\n- Read the [documentation](https://docs.cerbos.dev)\n- [Join the Cerbos community on Slack](http://go.cerbos.io/slack)\n- Email us at help@cerbos.dev\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbos%2Fcerbos-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerbos%2Fcerbos-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbos%2Fcerbos-sdk-python/lists"}