Skip to content

Cedarling Properties#

Cedarling bootstrap properties control the application's behavior. Properties common and specific to different authorization methods are described below.

Tip

Not sure which authorization method to use? See the decision guide.

Common properties#

These properties are effective regardless of which authorization method is in use.

Required properties#

  • CEDARLING_APPLICATION_NAME : Human-friendly identifier for this Cedarling instance.

Loading the policy store#

To load the policy store, one of the following properties must be set:

  • CEDARLING_POLICY_STORE_LOCAL_FN : Path to local policy store. Cedarling automatically detects the format as one of the following. This property is not supported in WASM due to lack of file-system access.

    • Directories --> loads as directory-based policy store
    • .cjar files --> loads as Cedar Archive
    • .yaml/.yml files --> loads as YAML (supported for test suites) (Note: Legacy .json files are no longer supported. Please migrate to the folder-based format or .cjar archive.)
  • CEDARLING_POLICY_STORE_URI : URL to fetch policy store archive from. The URL must point to a Cedar Archive (.cjar or zip archive). Legacy JSON endpoints are no longer supported.

  • CEDARLING_POLICY_STORE_LOCAL : Inline YAML policy store string (primarily supported for test suites and inline configurations). Inline JSON format is deprecated and rejected; migrate to folder-based .cjar archives, directories, or inline YAML.

Folder-Based Policy Store Format

Cedarling uses a folder-based policy store format with human-readable Cedar files (either as a directory or a .cjar archive). See Policy Store Formats for details.

Refreshing the policy store#

  • CEDARLING_POLICY_STORE_REFRESH_INTERVAL : Background refresh interval in seconds for URL-based policy store sources (CEDARLING_POLICY_STORE_URI pointing at a Cedar Archive URL). When set to a non-zero value, Cedarling spawns a worker that periodically re-fetches the policy store and atomically swaps the in-memory Authz instance when the upstream changes. A server-side Cache-Control: max-age / Expires hint may shorten the next interval but never extends it. Default is 0 (refresh disabled — load-once-at-startup behavior). Non-zero values below 5 seconds are clamped to 5. Ignored for local sources (CEDARLING_POLICY_STORE_LOCAL_FN, CEDARLING_POLICY_STORE_LOCAL). See Background refresh for the per-request consistency model, the strategy ladder, and the emitted metric keys.

Limiting policy store size#

  • CEDARLING_POLICY_STORE_MAX_FILE_SIZE : Maximum decompressed size, in bytes, of a single file inside a Cedar Archive (.cjar). Archives are ZIP files, so a small download can expand into a very large buffer in memory (a "zip bomb"); an archive whose entry exceeds this limit is rejected with an error rather than being decompressed. The whole-archive decompressed size is capped at ten times this value, and an archive may hold at most 10000 entries. Set to 0 to disable the size caps. Default is 10485760 (10 MB).

    This limit is independent of CEDARLING_HTTP_MAX_RESPONSE_SIZE_BYTES, which bounds the compressed archive while it is downloaded. Serving a .cjar over HTTP whose compressed size exceeds CEDARLING_HTTP_MAX_RESPONSE_SIZE_BYTES (10 MB by default) requires raising that property as well.

Verifying policy store signatures#

  • CEDARLING_POLICY_STORE_SIGSTORE_MODE : disabled (default) or enforce. With enforce, Cedarling loads a .cjar policy store only if its Sigstore (cosign keyless) bundle verifies against the signer below; otherwise loading fails and, on refresh, the current store is kept. Only .cjar sources can be signed, so enforce with a directory or YAML policy store fails at startup. Each verified load and refresh is logged at INFO with the signer identity, issuer, archive SHA-256 and Rekor timestamp.
  • CEDARLING_POLICY_STORE_SIGSTORE_CERT_IDENTITY : Expected signer identity (the certificate SAN), matched exactly. Required with enforce.
  • CEDARLING_POLICY_STORE_SIGSTORE_CERT_OIDC_ISSUER : Expected OIDC issuer of the signing certificate, matched exactly. Required with enforce.
  • CEDARLING_POLICY_STORE_SIGSTORE_BUNDLE_URI : Location of the bundle, as a URL for remote stores or a path for a local .cjar. Defaults to the policy store location with .sigstore.json appended. Required for archives passed as bytes (initFromArchiveBytes, load_from_json_with_archive_bytes), which have no location of their own.

These match the cosign verify-blob flags. For a policy store published by Agama Lab:

"CEDARLING_POLICY_STORE_SIGSTORE_MODE": "enforce",
"CEDARLING_POLICY_STORE_SIGSTORE_CERT_IDENTITY": "asset-signer@prod-gluu-cloud-platform.iam.gserviceaccount.com",
"CEDARLING_POLICY_STORE_SIGSTORE_CERT_OIDC_ISSUER": "https://accounts.google.com"

Optional properties#

Properties listed here are optional. If a property value is not set, the Cedarling will use the default value as specified in the property definition below.

Log behavior:

  • CEDARLING_LOG_TYPE : off, memory, std_out. Default is off.
  • CEDARLING_LOG_LEVEL : System Log Level See here. Default to WARN
  • CEDARLING_LOG_TTL : in case of memory store, TTL (time to live) of log entities in seconds.
  • CEDARLING_LOG_MAX_ITEMS : Maximum number of log entities that can be stored using Memory logger. If used 0 value means no limit. And If missed or None, default value is applied.
  • CEDARLING_LOG_MAX_ITEM_SIZE : Maximum size of a single log entity in bytes using Memory logger. If used 0 value means no limit. And If missed or None, default value is applied.
  • CEDARLING_STDOUT_MODE : Logging mode for stdout logger: async or immediate (default). Only applicable for native targets (not WASM). Defaults to immediate.
  • CEDARLING_STDOUT_TIMEOUT_MILLIS : Flush timeout in milliseconds for async stdout logging. Only applicable for native targets (not WASM). Defaults to 100 ms.
  • CEDARLING_STDOUT_BUFFER_LIMIT : Buffer size limit in bytes for async stdout logging. Only applicable for native targets (not WASM). Defaults to 1 MB (2^20 bytes).

Context Data API:

  • CEDARLING_DATA_STORE_MAX_ENTRIES : Maximum number of entries that can be stored in the data store. Default value is 10000. Set to 0 for unlimited entries.

  • CEDARLING_DATA_STORE_MAX_ENTRY_SIZE : Maximum size per entry in bytes. Default value is 1048576 (1 MB). Set to 0 for unlimited size.

  • CEDARLING_DATA_STORE_DEFAULT_TTL : Default TTL (Time To Live) in seconds for entries that don't specify a TTL. Default value is None (entries will not expire). When set, entries without an explicit TTL will use this value.

  • CEDARLING_DATA_STORE_MAX_TTL : Maximum allowed TTL in seconds. Default value is 3600 (1 hour). Entries with TTL exceeding this value will be rejected. Note: setting to 0 results in a zero-second max TTL (immediate expiry), not unlimited. There is currently no way to configure unlimited max TTL — omitting the property uses the default (1 hour).

  • CEDARLING_DATA_STORE_ENABLE_METRICS : Whether to enable metrics tracking for data entries (access counts, etc.). Default value is true.

  • CEDARLING_DATA_STORE_MEMORY_ALERT_THRESHOLD : Memory usage threshold percentage (0.0-100.0) for triggering alerts. Default value is 80.0. When capacity usage exceeds this threshold, memory_alert_triggered will be true in statistics.

Telemetry metrics:

  • CEDARLING_METRICS_COLLECTION : enabled | disabled. Whether to enable local collection of telemetry metrics, exposed via the drain_metrics API. drain_metrics is a destructive read: it returns a snapshot of the metrics and resets the interval window, so use a single consumer. It takes effect only when no Lock telemetry ticker is active; setting CEDARLING_LOCK_TELEMETRY_INTERVAL to a non-zero value makes the Lock ticker own the collector, even if the Lock server has no telemetry endpoint in which case the local metrics snapshot fails with LockTelemetry. Default is disabled.

HTTP client:

  • CEDARLING_HTTP_REQUEST_TIMEOUT : Per-request timeout in seconds. Only applicable for native targets (not WASM). Default is 10 (10 seconds).
  • CEDARLING_HTTP_REQUEST_MAX_RETRIES : Maximum number of retries per request. Only network failures and the statuses 408, 429 and 5xx are retried. Any other 4xx, an invalid URL or a refused redirect fails at once, because it would fail the same way again. A policy store fetched with the Lock Server's token also retries 401, because the Lock Server refuses a client for a few seconds after registering it. Applies to native and WASM builds. Default is 3.
  • CEDARLING_HTTP_REQUEST_RETRY_DELAY : Delay before the first retry, in seconds; it doubles with each retry, up to 5 minutes. Applies to native and WASM builds. Default is 3 (3 seconds).
  • CEDARLING_HTTP_MAX_RESPONSE_SIZE_BYTES : Maximum bytes Cedarling will buffer from any HTTP response (JWKS, OIDC discovery, status list, policy store, Lock Server). Oversized responses are rejected before they exhaust memory. Set to 0 to disable. Default is 10485760 (10 MB).

Advanced configuration:

  • CEDARLING_MAX_DEFAULT_ENTITIES : Maximum number of default entities that can be loaded from the policy store, counted before duplicate entities are merged. A store over the limit fails to load, at startup and on refresh. Set to 0 to disable; Cedarling then logs a warning at startup. Default is 1000.

Lock Server integration properties#

The following bootstrap properties are only needed for the Lock Server Integration. These apply to both authorization methods.

  • CEDARLING_LOCK : enabled | disabled. If enabled, the Cedarling will connect to the Lock Server for policies. Default is disabled.
  • CEDARLING_LOCK_SERVER_CONFIGURATION_URI : Required if LOCK == enabled. URI where Cedarling can get JSON file with all required metadata about the Lock Server, i.e. .well-known/lock-server-configuration. The URI must use https, or http only to a loopback host (localhost, 127.0.0.1, ::1); otherwise Cedarling fails to start. The Lock access token is sent to the endpoints this file lists, so a discovered log, health or telemetry endpoint that breaks the same rule is ignored with a warning, and Cedarling does not send that data. Unless CEDARLING_LOCK_ACCESS_TOKEN_JWT is set, Cedarling registers a client at the IdP this file names and sends the client secret, and the SSA if one is set, to the registration_endpoint and token_endpoint of the IdP's OpenID configuration; if either breaks the same rule, Cedarling fails to start.
  • CEDARLING_LOCK_SSA_JWT : SSA for DCR in a Lock Server deployment. The Cedarling will validate this SSA JWT prior to DCR.
  • CEDARLING_LOCK_ACCESS_TOKEN_JWT : Pre-issued access token for Lock Server. When set, Cedarling skips DCR and uses this token for every Lock Server request. Intended for testing and local development, or when DCR is not available. Cedarling cannot renew it: once it expires, Lock Server refuses the requests until Cedarling restarts with a new token. With TRACE enabled, the token must carry the trace.write scope, see Cedarling TRACE. Takes precedence over CEDARLING_LOCK_SSA_JWT; Cedarling logs a WARN when both are set. Not available on WASM builds.
  • CEDARLING_LOCK_LOG_INTERVAL : How often, in seconds, to send log messages to Lock Server. 0 turns transmission off. Default is 0.
  • CEDARLING_LOCK_HEALTH_INTERVAL : How often, in seconds, to send health messages to Lock Server. 0 turns transmission off. Default is 0.
  • CEDARLING_LOCK_TELEMETRY_INTERVAL : How often, in seconds, to send telemetry messages to Lock Server. 0 turns transmission off. Default is 0.
  • CEDARLING_LOCK_ACCEPT_INVALID_CERTS : enabled | disabled: Allows interaction with a Lock server with invalid certificates. Mainly used for testing. Doesn't work for WASM builds. Does not apply to TRACE over gRPC, see CEDARLING_TRACE_TRANSPORT. Default is disabled.
  • CEDARLING_LOCK_TRANSPORT : rest | grpc: Controls the transport protocol used to communicate with the Lock server. The gRPC transport requires compiling Cedarling with the grpc feature enabled. Does not affect TRACE, which has its own CEDARLING_TRACE_TRANSPORT. Default value is rest.
  • CEDARLING_LOCK_LOG_CHANNEL_CAPACITY : Channel capacity for buffering log entries before sending to the Lock Server. Higher values allow more buffering when the server is slow, but increase memory usage. Also the size of the TRACE record queue. Default is 100.
  • CEDARLING_LOCK_LOG_MAX_RETRIES : Maximum number of retries for sending a batch of logs or telemetry to the Lock Server. Uses exponential backoff: the delay doubles from 10 seconds up to 5 minutes. Only network failures, the statuses 401, 408, 429 and 5xx, the matching gRPC codes (UNAUTHENTICATED, UNAVAILABLE, INTERNAL, UNKNOWN, DEADLINE_EXCEEDED, CANCELLED, ABORTED), and a gRPC reply with success = false are retried. 401 is retried because the Lock Server refuses a client for a few seconds after registering it, and success = false because the Lock Server also sends it when storing the batch fails. Any other refusal by the Lock Server, or by a proxy before it (any other 4xx or gRPC code), drops the batch at once with one error, because the same batch would be refused again. Also applies to TRACE requests, which retry the same network failures, statuses and gRPC codes except 401 (UNAUTHENTICATED): TRACE then requests a new token and sends the request once more, and a second 401 is final, counted in trace.rejected. Default is 5.

TRACE properties#

TRACE makes Cedarling sign a record of each authorization decision that carries a TRACE context and send it to Lock Server. Requirements, the Auth Server and Lock Server setup, and troubleshooting are in Cedarling TRACE.

TRACE also uses two Lock properties: CEDARLING_LOCK_LOG_CHANNEL_CAPACITY is the size of its queue and CEDARLING_LOCK_LOG_MAX_RETRIES the number of retries. CEDARLING_LOCK_LOG_INTERVAL does not apply to TRACE.

  • CEDARLING_TRACE : enabled | disabled. Default is disabled.
  • CEDARLING_TRACE_PRODUCER_ID : Producer id signed into every record. 1 to 255 ASCII characters: a letter or digit, then letters, digits or ._:/-. Default is CEDARLING_APPLICATION_NAME, which must then follow the same rule (the default My App does not, because of the space). Lock Server must allow it, see Lock Server setup.
  • CEDARLING_TRACE_SIGNING_KEY : Path to the Ed25519 private key, an unencrypted PKCS#8 PEM file, for example from openssl genpkey -algorithm ed25519 -out trace-key.pem. With TRACE enabled, this property or CEDARLING_TRACE_SIGNING_KEY_PEM is required; when both are set, this one is used. Prefer it to the PEM property: a file, such as a mounted secret, keeps the key out of the configuration.
  • CEDARLING_TRACE_SIGNING_KEY_PEM : The same key as PEM text, for hosts that pass secrets only as values. Used only when CEDARLING_TRACE_SIGNING_KEY is not set. Treat a configuration that contains it as a secret: it can leak through environment dumps, process listings or version control.
  • CEDARLING_TRACE_SIGNING_KID : kid the key is registered under in Lock Server, at most 255 characters. Default is the key thumbprint, sha256:<hex>. Cedarling logs the producer id, kid and thumbprint at startup, for registering the key.
  • CEDARLING_TRACE_ENDPOINT : discovered or the URL of the TRACE bulk endpoint. Default is discovered: the trace_bulk_endpoint of the Lock Server configuration. A blank value also means discovered. The endpoint must use https, or http only to localhost, 127.0.0.1 or [::1], because requests carry the Lock access token; otherwise Cedarling logs a WARN and sends no records.
  • CEDARLING_TRACE_TRANSPORT : rest | grpc. Protocol for sending records. Default is rest.
    • grpc uses only the scheme, host and port of CEDARLING_TRACE_ENDPOINT. Lock Server and its proxy must serve TRACE over gRPC, see Lock Server gRPC transport. To reach a Lock Server gRPC port directly, set CEDARLING_TRACE_ENDPOINT to it, for example https://lock.example.com:50051.
    • grpc requires a build with the grpc feature.
    • Independent of CEDARLING_LOCK_TRANSPORT.
    • Over gRPC the Lock Server certificate is always verified: CEDARLING_LOCK_ACCEPT_INVALID_CERTS does not apply, and Cedarling logs a WARN when both are set.
  • CEDARLING_TRACE_BULK_MAX_RECORDS : Maximum number of records in one request. Greater than 0. Default is 100, the Lock Server default. Keep it at most the Lock Server traceConfiguration.maxBulkRecords.
  • CEDARLING_TRACE_BULK_MAX_BYTES : Maximum size of one request in bytes. At least 262146, so the largest record Lock Server accepts by default fits. Default is 4194304 (4 MiB), the Lock Server default. Keep it at most the Lock Server traceConfiguration.maxBulkRequestBytes.

authorize_multi_issuer method properties#

These properties are relevant only when using authorize_multi_issuer with signed JWT tokens from trusted identity providers. Also called Token-based Access Control (TBAC). This is the recommended authorization method for most production deployments.

JWT and cryptographic behavior:

  • CEDARLING_JWT_SIG_VALIDATION : enabled | disabled -- Whether to check the signature of all JWT tokens. When enabled, this requires the iss claim to be present in all tokens and the issuer URL must use the https scheme. Loopback hosts (localhost, 127.0.0.1, ::1) are allowed over plain HTTP so local development is not blocked. Default is enabled. Disabling this is strongly discouraged outside of testing: a JWT without signature validation is just plain JSON and is trivially spoofable.
  • CEDARLING_JWT_STATUS_VALIDATION : enabled | disabled -- Whether to check the status of the JWT. On startup, the Cedarling should fetch and retrieve the latest Status List JWT from the .well-known/openid-configuration via the status_list_endpoint claim and cache it. See the IETF Draft for more info. Default is enabled. If an issuer has no status_list_endpoint (including issuers with a static JWKS), the Cedarling logs a warning at startup and rejects that issuer's tokens that carry a status claim; tokens without one are not affected.
  • CEDARLING_STRICT_SCHEMA_VALIDATION : enabled | disabled -- When enabled (default), a Cedar schema is required and policies/entities are validated against it (current behavior). When disabled, Cedarling runs without schema-based validation, allowing quick-start and prototyping without maintaining a schema. If disabled and a schema is present, a warning is logged that the schema is loaded but not enforced. Default is enabled. Disabling this removes the load-time guard on attribute names and types. Typos in policies will silently fail to match and claim/attribute types are not validated. Keep enabled outside of prototyping.
  • CEDARLING_CUSTOM_TOKEN_PROCESSOR_TIMEOUT_MILLIS : Timeout in milliseconds applied to the custom token processor call for non-JWT custom tokens. 0 (default) disables the timeout.
  • CEDARLING_JWT_STATUS_LIST_REFRESH_INTERVAL_MAX : Upper bound on the Status List JWT refresh interval, in seconds. When the Status List JWT fetched from the issuer carries a ttl claim (per the IETF oauth-status-list spec), the effective refresh interval is min(jwt_ttl, CEDARLING_JWT_STATUS_LIST_REFRESH_INTERVAL_MAX) — the issuer can always request a more frequent refresh, but never a less frequent one. When the JWT omits ttl, this value is used directly. A value of 0 or an unset variable resolves to the built-in default (300 seconds) so the status list cannot silently go stale forever. Non-zero values below 5 are clamped to 5. Fail-closed semantics: if a background refresh fails (network error, 5xx, invalid status list body) the cached status list is dropped and all tokens that depend on it are rejected until the next successful refresh. This ensures a revoked token is never accepted based on stale data at the cost of temporarily denying valid tokens when the status endpoint is unreachable.
  • CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED : Only tokens signed with these algorithms are acceptable to the Cedarling. If not specified, all algorithms supported by the underlying library are allowed.
  • CEDARLING_LOCAL_JWKS : Path to a local file containing a JWKS. Keys from this file are loaded at startup and added to the key store before fetching remote issuer keys. Useful for development, testing, or air-gapped environments. Only used when CEDARLING_JWT_SIG_VALIDATION is enabled.
  • CEDARLING_JWKS_REFRESH_INTERVAL : Optional override for JWKS periodic refresh interval in seconds. When set, overrides the Cache-Control: max-age from the JWKS endpoint. If omitted, the server-driven interval or a 1-hour fallback is used.
  • CEDARLING_JWKS_REFRESH_MIN_INTERVAL : Minimum interval in seconds between on-demand JWKS re-fetches per issuer (those triggered by tokens with an unknown kid). Prevents abuse from invalid JWT floods triggering excessive re-fetches. Does not affect the periodic refresh schedule, which is driven by CEDARLING_JWKS_REFRESH_INTERVAL / Cache-Control: max-age. Default is 30 seconds.

Token cache:

  • CEDARLING_TOKEN_CACHE_MAX_TTL : Maximum token cache TTL in seconds. The token cache avoids decoding and validating the same token twice. Default is 5 seconds — small enough that revocation and status-list changes are picked up quickly, large enough to amortise repeated requests for the same token. Effective TTL is min(time-until-exp, max_ttl) when both apply. Setting this to 0 disables the token cache entirely.
  • CEDARLING_TOKEN_CACHE_CAPACITY : Maximum number of tokens the cache can store. Default value is 100. 0 means no limit.
  • CEDARLING_TOKEN_CACHE_EARLIEST_EXPIRATION_EVICTION : Enables eviction policy based on the earliest expiration time. When the cache reaches its capacity, the entry with the nearest expiration timestamp will be removed to make room for a new one. Default value is true.

Trusted issuer loading:

  • CEDARLING_TRUSTED_ISSUER_LOADER_TYPE : SYNC | ASYNC -- Type of trusted issuer loader. If not set, synchronous loader is used. Sync loader means that trusted issuers will be loaded on initialization. ASYNC loader means that trusted issuers will be loaded in background. Default is SYNC. When using ASYNC, see Trusted Issuer Loading Info to check loading status.
  • CEDARLING_TRUSTED_ISSUER_LOADER_WORKERS : Number of concurrent workers to use when loading trusted issuers. Applies to both SYNC (parallel loading during initialization) and ASYNC (parallel background loading) modes. Default is 10 for native targets (max 1000) or 2 for WASM targets (max 6). Values are clamped between 1 and the target-specific maximum. Zero becomes 1.

Decision logging for tokens:

  • CEDARLING_DECISION_LOG_DEFAULT_JWT_ID : JWT claim name used to identify tokens in decision logs. Default is jti. Override with any claim name (e.g., sub, sid) if your tokens lack a jti claim, or you need a different identifier.