Migrating from Cedar to Cerbos

AAlex OlivierOctober 18, 202614 min read
Migrating from Cedar to Cerbos

This guide is for you if your applications run the Cedar policy language themselves, through the Rust library, the Go implementation or a server your team built around them, and you are moving authorization to Cerbos. If you are doing the work, you get a full policy set translated to Cerbos with passing tests, the calls that replace the library, and a plan for running Cerbos beside Cedar before it enforces anything. If you are approving it, you get what changes for each team and how each step is checked.

Your rules stay the same. Owners still edit their documents, tenants still see what is shared with them, and anything on legal hold stays locked. What changes is everything around the rules. The server, the entity loading, the list filtering, the decision logs and the policy rollout you built around the Cedar library are replaced by one platform.

Why migrating from Cedar to Cerbos is mostly an authoring and data question

Cedar and Cerbos agree on the basics. Everything is denied unless a rule allows it, a deny overrides an allow, and policies are files you can review. So the translation is mostly mechanical. Permit becomes an allow rule, forbid becomes a deny rule, a when clause becomes a CEL condition, and a repeated condition becomes a derived role.

The bigger change is data. Today each service that calls Cedar assembles the entities a decision needs, the principal, the resource, their parents and attributes, and passes them in. After the move, most of those facts are attributes the service already has on the record, and the rest are fetched at decision time by Cerbos Synapse from the system that owns them. The code that builds Cedar entities in each service goes away.

For a CTO, that means one authorization service instead of a library, a server and a loader per stack. For an identity team, groups and attributes come from the directory they already govern. For a security team, every decision is logged with the policy version that made it, from the first day of shadow mode.

What replaces the Cedar library and the system around it

The Cedar library, the server you wrapped around it, the policy loading and the log pipeline go. In their place is one authorization platform, deployed where you need it.

  • Decisions run in Cerbos PDP, a stateless decision point next to each workload, as a sidecar, a service or inside AWS Lambda, on any cloud, on-premise or a hybrid mix under one set of policies, and in browsers and edge runtimes through the embedded PDP. Every language calls it through official SDKs.

  • Policy lives in Git or Cerbos Hub policy stores. Every change is tested before Cerbos Hub builds it, each decision point reports the build it runs, and an earlier build can be restored in one step.

  • Data that services used to assemble into Cedar entities is read where it lives. The application sends what it has, and Cerbos Synapse fetches the rest, cached for as long as you set per source.

  • Audit comes from decision logs that Cerbos Hub collects from every decision point, each tied to the policy version behind it.

Cerbos policy principles for teams used to writing Cedar

Policies are organized by resource. A resource policy holds every rule for one kind of resource, such as document, with the actions it supports. Conditions you repeat across policies become derived roles or variables.

Everything is denied unless a rule allows it, as in Cedar.

A deny for every role overrides any allow. Cedar's forbid always wins over a permit. In Cerbos, write the forbid as a deny rule for roles: ["*"] and it wins over every allow for that action, whichever role granted it.

Requests carry attributes, not an entity graph. The principal (P) and the resource (R) carry typed attributes, strings, numbers, booleans, lists and maps, and CEL conditions read them directly. Parents arrive as attributes, such as a list of folder IDs, sent by the application or fetched by Cerbos Synapse.

Grants are data. A share is a value on the record, not a new linked policy. One rule reads the list.

An error never widens access. A deny rule whose condition errors still denies, and an allow rule whose condition errors does not allow.

Cedar to Cerbos concept mapping

Cedar Cerbos Notes
Namespace and entity type, such as DocApp::Document Resource kind in a resource policy, document One policy file per kind
Principal entity type and its attributes Principal with roles and P.attr Groups and roles usually come from the identity provider
action in [...] actions: [...] on a rule
permit Rule with effect: EFFECT_ALLOW
forbid Rule with effect: EFFECT_DENY and roles: ["*"] Wins over every allow
when { ... } condition in CEL
unless { ... } condition with none, or the expression negated
A condition repeated across policies Derived role or variable Named once, reused by every rule
Policy template and template-linked policies A list attribute on the record, read by one rule A share becomes a row in your database, not a new policy
principal in Group::"x", entity parents A list attribute, such as P.attr.groups, or a Cerbos Synapse lookup Deep hierarchies resolved before the check
Entity tags, .hasTag(), .getTag() Map attributes, has() and map access
like with * matches with a regular expression, or startsWith and endsWith Escape special characters when converting
decimal, ip, datetime, duration extensions CEL numbers, inIPAddrRange, timestamp, duration, now() Compare decimal edge cases in tests, CEL uses doubles
context Principal or resource attributes, or JWT claims passed as auxiliary data
@id annotations Rule name Keeps the policy's name on the rule
Schema and cedar validate Schemas and cerbos compile Set schema enforcement to reject to catch missing attributes
cedar run-tests JSON tests Test suites in YAML Run in CI and in Cerbos Hub
is_authorized in the library CheckResources One call checks many actions on many resources
Partial evaluation PlanResources, a query plan your database runs Stable, with adapters
Diagnostics (determining policies) Response metadata (matchedPolicy per action, with includeMeta), and decision logs with the policy version Logs collected by Cerbos Hub
Cedar Analysis Test suites of the requests your people and records depend on, run in CI and in Cerbos Hub Every change is checked against those cases before it ships

A worked example of translating a Cedar policy set to Cerbos

Here is a policy set typical of a multi-tenant document app that runs Cedar itself. Owners can view, edit and delete their documents. Anyone in the same tenant can view a document shared with the tenant. People a document is shared with as editors can view and edit it, through a template. Nobody can edit or delete a document on legal hold.

// schema, docs.cedarschema
namespace DocApp {
 entity Tenant;
 entity User {
   tenant: Tenant,
 };
 entity Document {
   owner: User,
   tenant: Tenant,
   sharedWithTenant: Bool,
   legalHold: Bool,
 };
 action view, edit, delete appliesTo {
   principal: User,
   resource: Document,
 };
}
// policies.cedar
// Owners can view, edit and delete their own documents
@id("owner-full-access")
permit (
 principal,
 action in [DocApp::Action::"view", DocApp::Action::"edit", DocApp::Action::"delete"],
 resource
)
when { resource.owner == principal };
// Anyone in the same tenant can view a document shared with the tenant
@id("tenant-members-view-shared")
permit (
 principal,
 action == DocApp::Action::"view",
 resource
)
when { resource.sharedWithTenant && principal.tenant == resource.tenant };
// Nobody edits or deletes a document on legal hold
@id("legal-hold-blocks-changes")
forbid (
 principal,
 action in [DocApp::Action::"edit", DocApp::Action::"delete"],
 resource
)
when { resource.legalHold };
// Template, linked once for every person a document is shared with as an editor
@id("document-editor")
permit (
 principal == ?principal,
 action in [DocApp::Action::"view", DocApp::Action::"edit"],
 resource == ?resource
);

Each share links the template once, such as Bob as an editor of the roadmap, and your application stores and loads those linked policies. In Cerbos those links become a list on the document, editors, loaded with the document or fetched by Cerbos Synapse.

The decisions you know must hold today are the definition of a correct migration, so write them as a Cerbos test suite first, then make the policies pass. If you have Cedar tests for cedar run-tests, each request, entity set and expected decision becomes one principal, resource and expectation here.

# tests/document_test.yaml
name: DocumentTestSuite
principals:
 alice:
   id: alice
   roles: ["user"]
   attr: { tenant: acme }
 bob:
   id: bob
   roles: ["user"]
   attr: { tenant: acme }
 carol:
   id: carol
   roles: ["user"]
   attr: { tenant: acme }
 dave:
   id: dave
   roles: ["user"]
   attr: { tenant: globex }
resources:
 roadmap:
   kind: document
   id: roadmap
   attr:
     owner: alice
     tenant: acme
     sharedWithTenant: true
     legalHold: false
     editors: ["bob"]
 contract:
   kind: document
   id: contract
   attr:
     owner: alice
     tenant: acme
     sharedWithTenant: false
     legalHold: true
     editors: ["bob"]
tests:
 - name: Roadmap, shared with the tenant
   input:
     principals: ["alice", "bob", "carol", "dave"]
     resources: ["roadmap"]
     actions: ["view", "edit", "delete"]
   expected:
     - principal: alice
       resource: roadmap
       actions: { view: EFFECT_ALLOW, edit: EFFECT_ALLOW, delete: EFFECT_ALLOW }
     - principal: bob
       resource: roadmap
       actions: { view: EFFECT_ALLOW, edit: EFFECT_ALLOW, delete: EFFECT_DENY }
     - principal: carol
       resource: roadmap
       actions: { view: EFFECT_ALLOW, edit: EFFECT_DENY, delete: EFFECT_DENY }
     - principal: dave
       resource: roadmap
       actions: { view: EFFECT_DENY, edit: EFFECT_DENY, delete: EFFECT_DENY }
 - name: Contract, on legal hold and not shared
   input:
     principals: ["alice", "bob", "carol"]
     resources: ["contract"]
     actions: ["view", "edit", "delete"]
   expected:
     - principal: alice
       resource: contract
       actions: { view: EFFECT_ALLOW, edit: EFFECT_DENY, delete: EFFECT_DENY }
     - principal: bob
       resource: contract
       actions: { view: EFFECT_ALLOW, edit: EFFECT_DENY, delete: EFFECT_DENY }
     - principal: carol
       resource: contract
       actions: { view: EFFECT_DENY, edit: EFFECT_DENY, delete: EFFECT_DENY }

The conditions you repeat become derived roles, so the resource policy can refer to them by name.

# derived_roles/document_roles.yaml
apiVersion: api.cerbos.dev/v1
derivedRoles:
 name: document_roles
 definitions:
   # Cedar: when { resource.owner == principal }
   - name: owner
     parentRoles: ["user"]
     condition:
       match:
         expr: R.attr.owner == P.id


   # Cedar: when { principal.tenant == resource.tenant }
   - name: tenant_member
     parentRoles: ["user"]
     condition:
       match:
         expr: R.attr.tenant == P.attr.tenant


   # Cedar: the document-editor template and its links
   - name: editor
     parentRoles: ["user"]
     condition:
       match:
         expr: P.id in R.attr.editors

The resource policy holds the rules, one per Cedar policy, and the forbid becomes a deny for every role.

# resources/document.yaml
apiVersion: api.cerbos.dev/v1
resourcePolicy:
 version: default
 resource: document
 importDerivedRoles:
   - document_roles
 rules:
   # Cedar: owner-full-access
   - name: owner-full-access
     actions: ["view", "edit", "delete"]
     effect: EFFECT_ALLOW
     derivedRoles: ["owner"]


   # Cedar: tenant-members-view-shared
   - name: tenant-members-view-shared
     actions: ["view"]
     effect: EFFECT_ALLOW
     derivedRoles: ["tenant_member"]
     condition:
       match:
         expr: R.attr.sharedWithTenant


   # Cedar: document-editor template
   - name: editors-view-and-edit
     actions: ["view", "edit"]
     effect: EFFECT_ALLOW
     derivedRoles: ["editor"]


   # Cedar: legal-hold-blocks-changes (forbid)
   - name: legal-hold-blocks-changes
     actions: ["edit", "delete"]
     effect: EFFECT_DENY
     roles: ["*"]
     condition:
       match:
         expr: R.attr.legalHold

A few things changed on the way across. The Cedar entity type became the policy's resource. The owner, tenant and editor conditions became derived roles that any rule can reuse. The forbid became a deny for every role, so the owner of the contract cannot edit it while it is on legal hold, exactly as in Cedar. The template and its links became one rule over a list, so sharing a document with a new editor is a row in your database rather than another linked policy to store and load. Run cerbos compile locally or in CI, or let Cerbos Hub run the suite before it builds the deployment, and the policies only ship when all 21 tests pass.

If your team works with an AI coding agent, the Cerbos agent skills help with the rewrite. Install them with npx skills add cerbos/skills, give the agent your rules written in plain words, and it writes each one as a Cerbos policy with a test suite and runs the tests until they pass. Your reviewers still approve every policy before it ships.

migrating-from-cedar-to-cerbos-cedar-policy-to-cerbos-policy-to-test.png

Where your Cedar entity data goes after the migration

List what each service loads into Cedar today, entity by entity, and find where each fact already lives.

  • Attributes on the resource, such as owner, tenant, status and legal hold, are usually columns on the record the service just read. Send them as resource attributes.

  • Principal attributes and groups belong to your identity provider. They arrive in the person's token, or Cerbos Synapse reads them from Okta, Entra ID or another directory at decision time. Read through Cerbos Synapse, a change in the directory applies within the cache time you set. Read from a token, it waits until the token is reissued.

  • Parents and hierarchies, such as folders or organizational units, become a list attribute for shallow trees. For deep trees, Cerbos Synapse queries the tree where it lives and returns the answer, and CEL hierarchy functions cover organization paths.

  • Template links become a list on the record, such as editors, as in the example.

  • Context, such as the request's IP address or time, becomes a principal or resource attribute, or JWT claims passed as auxiliary data.

Once each fact has a home, the entity loaders in each service can be deleted.

Replacing Cedar's library calls with Cerbos

is_authorized becomes CheckResources

A Cedar call passes a request, the policy set and the entities to the library. A Cerbos call sends the principal and the resource with their attributes to Cerbos PDP, and can ask about several actions on several resources at once.

import { GRPC } from "@cerbos/grpc";


const cerbos = new GRPC("localhost:3593", { tls: false });


const decision = await cerbos.checkResource({
 principal: { id: user.id, roles: ["user"], attr: { tenant: user.tenantId } },
 resource: {
   kind: "document",
   id: doc.id,
   attr: {
     owner: doc.ownerId,
     tenant: doc.tenantId,
     sharedWithTenant: doc.sharedWithTenant,
     legalHold: doc.legalHold,
     editors: doc.editorIds,
   },
 },
 actions: ["view", "edit", "delete"],
});


if (!decision.isAllowed("edit")) {
 throw new ForbiddenError();
}

Official SDKs cover JavaScript, Go, Python, Java, .NET, Rust, PHP and Ruby, so each service keeps its language and loses its Cedar binding.

Partial evaluation becomes PlanResources

If you built list filtering on Cedar's partial evaluation, replace it with a query plan. PlanResources turns the policy into a filter, and an adapter adds it to the query you already run, so the database returns the documents a person can see, sorted and paginated as usual. Documented adapters cover Prisma, Drizzle, Mongoose, Convex, SQLAlchemy and LangChain with ChromaDB.

Your Cedar server and policy loading

If you wrapped Cedar in a service, its API, its policy loading and its reload logic are replaced by Cerbos PDP and Cerbos Hub. Point each service at its local decision point, and let Cerbos Hub deliver policy updates.

Running Cerbos beside Cedar in shadow mode

Until Cerbos has matched Cedar on real traffic, Cedar stays in charge. Each request goes to both, and the Cerbos call runs in the background, so an error or a slow response from Cerbos never reaches the user.

// principal and resource built as in the CheckResources example above
const cedarAllowed = cedarAuthorize(user, "edit", doc);


cerbos
 .checkResource({ principal, resource, actions: ["edit"] })
 .then((d) => {
   if (cedarAllowed !== d.isAllowed("edit")) {
     logger.warn("authz_mismatch", { docId: doc.id, userId: user.id, cedarAllowed });
   }
 })
 .catch((err) => logger.error("cerbos_shadow_error", { docId: doc.id, err }));


return cedarAllowed;

Early mismatches usually trace back to data, such as a missing resource attribute or a group that was never put in the token. Look closely at any mismatch on a forbid. Cedar skips a policy whose condition errors, while a Cerbos deny with an erroring condition still denies, so a mismatch there can be a Cedar policy that was never blocking what it was written to block. Every Cerbos decision in the comparison is already in Cerbos Hub's decision log, with the policy version beside it.

Switching over and decommissioning the Cedar library

Move one service at a time. Once a service has gone through a full business cycle in shadow mode and every mismatch has an explanation, Cerbos starts enforcing for it. Leave the Cedar call running in the background for a few days, so you can switch back without a deploy. After the last service moves, remove the Cedar library, the server around it, the entity loaders and the log pipeline.

migrating-from-cedar-to-cerbos-moving-off-cedar-one-service-at-a-time.png

Common challenges when migrating from Cedar, and how to solve them

Deep entity hierarchies. Do not send the whole tree in the request. Let Cerbos Synapse query it and return what the policy needs, such as the folders a person can view.

Many linked templates. Each linked policy is a grant. Export them once, group them by template, and load each group into a list column on the record.

like patterns. Convert each to matches, startsWith or endsWith, escaping regular expression characters, and cover the edge cases in tests.

Decimal values. Cedar's decimal has four decimal places (Cedar documentation, read November 2026). CEL uses doubles, so test boundary values such as limits and thresholds explicitly.

Durations in days. Cedar durations accept a day unit. Cerbos durations are written in hours, minutes and seconds, so convert 1d to 24h when translating.

Forbid rules that errored silently in Cedar. A deny in Cerbos still applies when its condition errors, so a request Cedar used to allow can start being denied. Mark required attributes in a schema and set enforcement to reject, so a request missing one is denied for every action and the response lists the validation error.

Policy sets that drifted between bindings. Services on different Cedar bindings may have ended up with different policies, since cedar-go has no templates. Translate each set, then run every service's policies against one Cerbos test suite, so any difference shows up as a failing test.

Planning your Cedar migration

Start with one service that calls Cedar often and has a small policy set. Write its decisions as a test suite, translate the policies, run it in shadow mode, then cut it over. The second service often needs less data work, because many of its groups and lookups are the ones the first service already uses.

As Joe Qureshi, Senior Software Engineer at 9fin, put it, "Cerbos has a pattern of having a single microservice so that we could gradually roll out the rules to other services beyond the main web app."


Try Cerbos with one service's Cedar policies. Your engineers retire the server and entity loaders they built around the library, your identity team's directory becomes the one source of groups for every service that moves, and your security team gets decision logs with the policy version for every service as it moves.

To plan the move from Cedar, book a call with our team. Bring the policies of the service you want to move first, and leave with the first service to move, its translated policies and tests, and a shadow mode plan your reviewers can sign off.

Go deeper:

FAQ

Tagged in

Free policy workshop

Get your first Cerbos policy written by our team.

Book a session to talk through your requirements and walk away with a working policy.

Book a session