Skip to main content

What is Cedarling?

Understand Cedarling's authorization model and the full path from policy authoring and verified releases to application enforcement, Lock distribution, and signed evidence.

On this page

What Cedarling helps protect

Signing in establishes who a user is. Your application still needs to decide which records they may read, which operations they may perform, and which tools an agent may use on their behalf.

Cedarling is an embeddable policy decision point built on the Rust Cedar engine. It evaluates authorization requests against Cedar policies, close to the application or service that needs the answer. The application enforces the result before releasing data or performing an action.

The official Cedarling overview (external site, opens in a new tab) describes its components and supported environments. Building a solution around it also involves trusted identity, policy delivery, and records of what was decided and done.

How a decision works

Cedar is the policy language and evaluation model. Cedarling adds interfaces for initialization, identity evidence, request evaluation, context data, and logging.

A Cedar authorization request has four parts, often called P-A-R-C:

Part Question Refund-approval example
Principal Who is requesting access? A reviewer or an agent acting for that reviewer
Action What do they want to do? ApproveRefund
Resource What is affected? A particular refund request
Context Which additional facts matter? The request time or an approval limit

Policies can use roles, ownership relationships, and other attributes to express business rules. If no permit policy matches, Cedar denies the request. A matching forbid policy overrides permits. The schema defines the shapes policies may use; it does not grant permission. See the Cedar authorization guide (external site, opens in a new tab).

Cedarling is the Policy Decision Point (PDP). It returns ALLOW or DENY with a request identifier and available diagnostics. Your application, API, or gateway is the Policy Enforcement Point (PEP). It obtains trusted facts and acts on the decision. For ApproveRefund, ALLOW permits recording an approval; issuing the payment is a separate operation to protect.

Supply identity evidence and current facts

The authorization reference (external site, opens in a new tab) describes two ways to supply identity evidence.

Token-based access control

Token-Based Access Control (TBAC) uses signed tokens from trusted issuers as evidence for a decision. Jans Auth or an existing identity provider issues the tokens; Cedarling validates them according to its configured trust, token mappings, and claim requirements.

In JavaScript, authorizeMultiIssuer accepts one or more mapped tokens. A request can use a single issuer. Validated token entities appear under context.tokens; policies read their claims there instead of treating one token as a conventional Cedar principal. A valid token supplies evidence, while the policies determine whether that evidence permits the requested action.

Application-established identity

With authorizeUnsigned, the application supplies the principal and related entities directly. Cedarling does not validate a JWT on this path. The trusted caller is responsible for authenticating the principal and supplying authentic facts. This supports systems that have already established identity upstream.

Current application facts

Token claims alone may not describe a resource's current owner, tenant, or workflow state. The application reads those facts from its trusted systems and includes them in the request.

For shared dynamic values, the Context Data API (external site, opens in a new tab) lets an application push data into Cedarling under context.data, with an optional time to live (TTL). Expiry limits how long a value remains available; the application still owns its accuracy and refresh schedule. Cedarling evaluates the supplied data rather than querying business systems during a decision.

What a policy store contains

A policy store packages the rules and supporting definitions Cedarling loads for evaluation. The directory-based format keeps that source readable:

  • metadata.json identifies and versions the store.
  • schema.cedarschema or schemas/ defines entity types, actions, and context shapes. Choose one schema layout.
  • policies/ contains Cedar permit and forbid policies.
  • Optional templates/ and entities/ hold policy templates and default entities.
  • Optional trusted-issuers/ and custom-issuers/ configure JWT issuers and registered non-JWT token processors.

Use default entities for stable shared data and request entities for current facts. For distribution, package the directory contents at the root of a .cjar ZIP archive. The Cedarling policy-store reference (external site, opens in a new tab) defines its exact layout and configuration.

The AuthZEN Policy Store draft (external site, opens in a new tab) proposes a portable authorization-artifact format across policy engines. It is a draft, not a ratified standard or a guarantee of full Cedarling compatibility. It is separate from the AuthZEN Authorization API used to exchange decisions.

From policy authoring to enforced access

Policy delivery and request handling meet at the running Cedarling instance. The full lifecycle includes both:

1. Author and test the rules

Define the actions, resources, and facts the business needs to protect. Write the schema and policies with Cedar tooling or Agama Lab Cedar Policy Designer (external site, opens in a new tab). Test permitted and denied requests, including missing facts and cross-tenant attempts.

For ApproveRefund, identify the operation that saves the approval and the facts needed to authorize it.

2. Review the source

Review policy changes and test results in Git before approving a release. Check that the rules express the intended business permission and that the application supplies the facts they require.

3. Publish a versioned release

The release workflow packages the reviewed source. Agama Lab releases (external site, opens in a new tab) publish the .cjar, a .cjar.sha256sum checksum file, and a .cjar.sigstore.json signature bundle. Keep the store ID, version, and archive hash associated with the deployment so an operator can identify which release was loaded.

4. Verify bytes and publisher

Before deployment, compare the archive's SHA-256 digest with its checksum file. Use Sigstore's cosign verify-blob with the signature bundle, expected signer identity, and expected OpenID Connect (OIDC) issuer for the signing certificate. These identify the artifact publisher, independently of your application's token issuers. Obtain the expected values from trusted release configuration, separately from the download. The cosign verification guide (external site, opens in a new tab) explains the procedure.

A checksum alone cannot authenticate a publisher. Signature verification binds a publisher to particular bytes; policy review and tests establish whether the rules are appropriate. Reject failed verification and load the exact bytes that passed it. Any change to those bytes invalidates the original signature.

5. Distribute the verified store

Janssen Lock Server (external site, opens in a new tab) is a Policy Retrieval Point: it retrieves and caches policy stores and makes them available to Cedarling instances. It can also collect decision logs. Protect policy retrieval and log delivery with authenticated connections and separate access controls.

Lock is optional. An application can receive a verified archive through its own artifact-delivery system and load it directly. Whichever delivery path you choose, ensure Cedarling loads the same bytes your deployment workflow verified.

6. Initialize Cedarling

Load bootstrap configuration, the startup settings for policy loading, token validation, and logging, along with the selected policy store. For token-based authorization, initialization also loads configured issuer metadata and verification keys. Handle initialization failures before accepting protected requests. Reuse the instance across requests and release its resources using the selected binding's lifecycle methods.

7. Evaluate the current request

At the protected operation, the application gathers the action, resource, current context, and identity evidence. It calls the appropriate authorization interface. Cedarling evaluates the request against the loaded store and returns a decision with diagnostics.

Distinguish a policy DENY from malformed input, configuration problems, and runtime errors. They need different operational handling, even though none permits the protected operation to proceed.

8. Enforce before the effect

The application records the refund approval only after ALLOW for that request. DENY, errors, and unavailable decisions block the approval. A hidden or disabled button cannot replace this check: direct API requests must pass through the same enforcement point.

Use facts that remain valid for the operation being committed. If ownership or workflow state changes before execution, obtain a decision for the current state rather than reusing an earlier permission.

9. Retain logs and signed evidence

Configure decision and system logs (external site, opens in a new tab) for investigation and operations. Cedarling supports in-memory retrieval and centralized log delivery through Lock. Limit retention and access; exclude raw tokens, secrets, and unnecessary sensitive data.

Signed TRACE evidence adds attributable records of decisions and invocations. In the Lock TRACE model (external site, opens in a new tab):

  • A PDP produces AUTHORIZATION_DECISION, identifying the decision and policy-store release.
  • An enforcement point produces CAPABILITY_INVOKED for an invocation it mediated.
  • An observer may produce RUNTIME_EFFECT for an effect it observed.

The caller supplies trace_execution_id and execution_authority to associate records with an execution. Lock checks signatures against registered producer keys authorized for the event kind, stores accepted assertions unchanged, and supports retrieval by execution or policy-store release. OAuth controls API access separately from producer-signature verification.

Cedarling server and sidecar builds sign and send AUTHORIZATION_DECISION records to Lock today; the browser (WASM) build does not emit TRACE. Check a signed record in your browser. Setting the diagnostic log level to TRACE does not enable signed evidence.

A valid signature identifies the signer and detects changes to signed fields. It does not prove truth, complete reporting, successful enforcement, or causation. Policy-release signatures and TRACE records serve different purposes: one verifies the artifact publisher, while the other attributes a runtime assertion to its producer.

Where Cedarling runs

Choose the integration boundary according to where your application owns the protected resource:

Deployment Integration
Browser The WASM binding evaluates policies inside JavaScript, for example to guide available controls.
Mobile Native bindings embed Cedarling in an iOS or Android application.
Backend A language binding embeds Cedarling in a service, gateway, database integration, or worker.
Sidecar A separate Dockerized Flask service receives authorization requests from a nearby application.

Embedded applications call their binding directly. The Cedarling sidecar (external site, opens in a new tab) exposes an HTTP authorization interface based on the AuthZEN Authorization API (external site, opens in a new tab), which defines exchanges between PEPs and PDPs. Protect this service endpoint with authentication and restricted network access.

A browser decision can guide the interface, but the trusted service that owns server-side data or effects must make and enforce its own decision. The same rule applies to agent tools: permission to attempt a tool call must be checked where the tool is executed.

Start building

Start with the protected operation and its trusted facts, then select an integration:

We use analytics cookies to measure which pages are useful, so we can improve them. They are only set if you accept. Essential cookies needed for the site to work are always on. See our privacy policy.