{"id":18715157,"url":"https://github.com/cerbos/cerbos-sdk-java","last_synced_at":"2025-09-02T02:34:20.132Z","repository":{"id":38237868,"uuid":"397982717","full_name":"cerbos/cerbos-sdk-java","owner":"cerbos","description":"Java SDK for interacting with the Cerbos PDP.","archived":false,"fork":false,"pushed_at":"2025-08-25T06:46:51.000Z","size":831,"stargazers_count":11,"open_issues_count":3,"forks_count":9,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-08-29T08:43:45.761Z","etag":null,"topics":["access-control","cerbos","policy","security"],"latest_commit_sha":null,"homepage":"https://cerbos.dev","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cerbos.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2021-08-19T15:04:00.000Z","updated_at":"2025-08-25T06:46:53.000Z","dependencies_parsed_at":"2023-02-11T03:30:34.621Z","dependency_job_id":"da150236-f9e7-4aae-8794-db3c0e7e43ff","html_url":"https://github.com/cerbos/cerbos-sdk-java","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/cerbos/cerbos-sdk-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerbos","download_url":"https://codeload.github.com/cerbos/cerbos-sdk-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerbos%2Fcerbos-sdk-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273220470,"owners_count":25066394,"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","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","cerbos","policy","security"],"created_at":"2024-11-07T13:07:45.776Z","updated_at":"2025-09-02T02:34:20.113Z","avatar_url":"https://github.com/cerbos.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Cerbos Java SDK\n===============\n\n![Maven Central](https://img.shields.io/maven-central/v/dev.cerbos/cerbos-sdk-java?style=for-the-badge\u0026versionPrefix=0.)\n\nJava client library for the [Cerbos](https://github.com/cerbos/cerbos) open source access control solution. This library\nincludes RPC clients for accessing the Cerbos PDP and test utilities for testing your code locally\nusing [Testcontainers](https://www.testcontainers.org).\n\nFind out more about Cerbos at https://cerbos.dev and read the documentation at https://docs.cerbos.dev.\n\nInstallation\n-------------\n\nArtifacts are available from Maven Central.\n\n**Example: Gradle (Kotlin DSL)**\n\n```kotlin\ndependencies {\n    implementation(\"dev.cerbos:cerbos-sdk-java:0.+\")\n    implementation(\"io.grpc:grpc-core:1.+\")\n}\n\nrepositories {\n    mavenCentral()\n}\n```\n\nExamples\n--------\n\n\u003e [!NOTE]\n\u003e Connecting to Unix domain sockets using this SDK is only supported on Linux, which is a limitation inherited from the underlying [`grpc-java`](https://github.com/grpc/grpc-java) library.\n\n### Creating a client without TLS\n\n```java\nCerbosBlockingClient client=new CerbosClientBuilder(\"localhost:3593\").withPlaintext().buildBlockingClient();\n```\n\n### Check a single principal and resource\n\n```java\nCheckResult result=client.check(\n    Principal.newInstance(\"john\",\"employee\")\n        .withPolicyVersion(\"20210210\")\n        .withAttribute(\"department\",stringValue(\"marketing\"))\n        .withAttribute(\"geography\",stringValue(\"GB\")),\n    Resource.newInstance(\"leave_request\",\"xx125\")\n        .withPolicyVersion(\"20210210\")\n        .withAttribute(\"department\",stringValue(\"marketing\"))\n        .withAttribute(\"geography\",stringValue(\"GB\"))\n        .withAttribute(\"owner\",stringValue(\"john\")),\n    \"view:public\",\"approve\");\n\nif(result.isAllowed(\"approve\")){ // returns true if `approve` action is allowed\n    ...\n}\n```\n\n### Check a batch\n\n```java\nCheckResourcesResult result=client.batch(\n    Principal.newInstance(\"john\",\"employee\")\n        .withPolicyVersion(\"20210210\")\n        .withAttribute(\"department\",stringValue(\"marketing\"))\n        .withAttribute(\"geography\",stringValue(\"GB\"))\n    )\n    .addResources(\n        ResourceAction.newInstance(\"leave_request\",\"XX125\")\n            .withPolicyVersion(\"20210210\")\n            .withAttributes(\n                Map.of(\n                    \"department\", stringValue(\"marketing\"),\n                    \"geography\", stringValue(\"GB\"),\n                    \"owner\", stringValue(\"john\")\n                )\n            )\n            .withActions(\"view:public\",\"approve\",\"defer\"),\n        ResourceAction.newInstance(\"leave_request\",\"XX225\")\n            .withPolicyVersion(\"20210210\")\n            .withAttributes(\n                Map.of(\n                    \"department\", stringValue(\"marketing\"),\n                    \"geography\", stringValue(\"GB\"),\n                    \"owner\", stringValue(\"martha\")\n                )\n            )\n            .withActions(\"view:public\",\"approve\"),\n        ResourceAction.newInstance(\"leave_request\",\"XX325\")\n            .withPolicyVersion(\"20210210\")\n            .withAttributes(\n                Map.of(\n                    \"department\", stringValue(\"marketing\"),\n                    \"geography\", stringValue(\"US\"),\n                    \"owner\", stringValue(\"peggy\")\n                )\n            )\n            .withActions(\"view:public\",\"approve\")\n    )\n    .check();\n\nresult.find(\"XX125\").map(r-\u003er.isAllowed(\"view:public\")).orElse(false);\n```\n\n### Create a query plan\n\n```java\nPlanResourcesResult result = client.plan(\n    Principal.newInstance(\"maggie\",\"manager\")\n        .withAttribute(\"department\",stringValue(\"marketing\"))\n        .withAttribute(\"geography\",stringValue(\"GB\"))\n        .withAttribute(\"team\",stringValue(\"design\")),\n    Resource.newInstance(\"leave_request\").withPolicyVersion(\"20210210\"),\n    \"approve\"\n);\n\nif(result.isAlwaysAllowed()) {\n    return true;\n} else if(result.isAlwaysDenied()) {\n    return false;\n} else {\n    return executeQuery(result.getCondition());\n}\n```\n\n### Test with [Testcontainers](https://www.testcontainers.org)\n\n```java\n@Container\nprivate static final CerbosContainer cerbosContainer=new CerbosContainer()\n    .withClasspathResourceMapping(\"policies\",\"/policies\",BindMode.READ_ONLY)\n    .withLogConsumer(new Slf4jLogConsumer(LOG));\n\n@BeforeAll\nprivate void initClient() throws CerbosClientBuilder.InvalidClientConfigurationException{\n    String target=cerbosContainer.getTarget();\n    this.client=new CerbosClientBuilder(target).withPlaintext().buildBlockingClient();\n}\n```\n\n### Accessing the Admin API\n\n```java\n// Username and password can be specified using CERBOS_USER and CERBOS_PASSWORD environment variables as well\nCerbosBlockingAdminClient  adminClient = new CerbosClientBuilder(target).withPlaintext().buildBlockingAdminClient(\"username\", \"password\");\n\nadminClient.addOrUpdatePolicy().with(new FileReader(fileObjectContainingPolicyJSON)).addOrUpdate();\n```\n\nSee `CerbosBlockingAdminClientTest` test class for more examples of Admin API usage including how to convert YAML policies to the JSON format required by the  API.\n\n## Connecting to Cerbos Hub stores\n\nLog in to Cerbos Hub and generate a client credential for the store you wish to connect. Create two environment variables named `CERBOS_HUB_CLIENT_ID` and `CERBOS_HUB_CLIENT_SECRET` to hold the credentials.   \n\n```java\nCerbosHubStoreClient client = CerbosHubClientBuilder.fromEnv().build().storeClient();\ntry {\n    Store.ReplaceFilesResponse resp = client.replaceFiles(Store.newReplaceFilesRequest(storeID, \"Reset store\", Utils.createZip(\"path/to/dir\")));\n    System.out.println(resp.getNewStoreVersion());\n} catch (StoreException se) {\n    ...\n}\n```\n\nIt's possible to obtain more information about errors by catching the specific exception class (e.g. `dev.cerbos.sdk.hub.exceptions.ValidationFailureException`) or by catching `dev.cerbos.sdk.hub.exceptions.StoreException`, calling `getReason()` to determine the reason for the exception and then casting the exception to the appropriate exception subclass.\n\n```java\n// Catching a specific exception\ntry {\n    Store.ReplaceFilesResponse resp = client.replaceFiles(Store.newReplaceFilesRequest(storeID, \"Reset store\", Utils.createZip(\"path/to/dir\")));\n    System.out.println(resp.getNewStoreVersion());\n        } catch (NoUsableFilesException nufe) {\n        nufe.getIgnoredFiles().stream().forEach(System.out::println);\n} catch (StoreException se) {\n        // Catch-all \n}\n\n// Catching StoreException and casting\ntry {\n    Store.ReplaceFilesResponse resp = client.replaceFiles(Store.newReplaceFilesRequest(storeID, \"Reset store\", Utils.createZip(\"path/to/dir\")));\n    System.out.println(resp.getNewStoreVersion());\n        } catch (StoreException se) {\n        if (se.getReason() == StoreException.Reason.NO_USABLE_FILES) {\nNoUsableFilesException exception = (NoUsableFilesException) se;\n        exception.getIgnoredFiles().stream().forEach(System.out::println);\n    }\n}\n```\n\n## Common issues\n\n`java.lang.IllegalArgumentException: cannot find a NameResolver for ...`:\n   The gRPC library relies on Java SPI to register name resolvers and client-side load balancing strategies for clients. The defaults are defined in the `io.grpc:grpc-core` library. Some packaging methods could overwrite or strip out the `META-INF/services` directory, which would cause the above exception on Cerbos client initialisation. If that's the case, eithertry to recreate the [default service bindings](https://github.com/grpc/grpc-java/tree/master/core/src/main/resources/META-INF/services) in your own jar OR explicitly register the services as follows:\n\n   ```java\n   import io.grpc.LoadBalancerRegistry;\n   import io.grpc.NameResolverRegistry;\n\n   public class Cerbos {\n     public static void main(String[] args) throws CerbosClientBuilder.InvalidClientConfigurationException {\n       LoadBalancerRegistry.getDefaultRegistry().register(new io.grpc.internal.PickFirstLoadBalancerProvider());\n       NameResolverRegistry.getDefaultRegistry().register(new io.grpc.internal.DnsNameResolverProvider());\n       CerbosBlockingClient client = new CerbosClientBuilder(\"dns:///cerbos.my-ns.svc.cluster.local:3593\").withInsecure().buildBlockingClient();\n       ...\n     }\n   }\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbos%2Fcerbos-sdk-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerbos%2Fcerbos-sdk-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerbos%2Fcerbos-sdk-java/lists"}