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.jsonidentifies and versions the store.schema.cedarschemaorschemas/defines entity types, actions, and context shapes. Choose one schema layout.policies/contains Cedar permit and forbid policies.- Optional
templates/andentities/hold policy templates and default entities. - Optional
trusted-issuers/andcustom-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_INVOKEDfor an invocation it mediated. - An observer may produce
RUNTIME_EFFECTfor 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:
- Use the Cedarling interfaces (external site, opens in a new tab) to initialize an instance and evaluate requests. The JavaScript package (external site, opens in a new tab) provides the WASM binding.
- Read the solution architecture and policy-store lifecycle to choose identity, policy delivery, and evidence components for your environment.
- Follow the application tutorials to build and verify enforcement in a working project.
- Try policy decisions in the Playground. Most samples use application-established identity; Google Trusted Identity uses a site-configured OIDC flow and keeps the returned ID token in the current tab. Use only fictional data and never paste tokens, secrets, or production policy material into a sample.
