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
.cjarfiles --> loads as Cedar Archive.yaml/.ymlfiles --> loads as YAML (supported for test suites) (Note: Legacy.jsonfiles are no longer supported. Please migrate to the folder-based format or.cjararchive.)
-
CEDARLING_POLICY_STORE_URI: URL to fetch policy store archive from. The URL must point to a Cedar Archive (.cjaror 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.cjararchives, 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_URIpointing 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-memoryAuthzinstance when the upstream changes. A server-sideCache-Control: max-age/Expireshint may shorten the next interval but never extends it. Default is0(refresh disabled — load-once-at-startup behavior). Non-zero values below5seconds are clamped to5. 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 to0to disable the size caps. Default is10485760(10 MB).This limit is independent of
CEDARLING_HTTP_MAX_RESPONSE_SIZE_BYTES, which bounds the compressed archive while it is downloaded. Serving a.cjarover HTTP whose compressed size exceedsCEDARLING_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) orenforce. Withenforce, Cedarling loads a.cjarpolicy 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.cjarsources can be signed, soenforcewith a directory or YAML policy store fails at startup. Each verified load and refresh is logged atINFOwith 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 withenforce.CEDARLING_POLICY_STORE_SIGSTORE_CERT_OIDC_ISSUER: Expected OIDC issuer of the signing certificate, matched exactly. Required withenforce.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.jsonappended. 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 isoff.CEDARLING_LOG_LEVEL: System Log Level See here. Default toWARNCEDARLING_LOG_TTL: in case ofmemorystore, 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 used0value 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 used0value means no limit. And If missed or None, default value is applied.CEDARLING_STDOUT_MODE: Logging mode for stdout logger:asyncorimmediate(default). Only applicable for native targets (not WASM). Defaults toimmediate.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 is10000. Set to0for unlimited entries. -
CEDARLING_DATA_STORE_MAX_ENTRY_SIZE: Maximum size per entry in bytes. Default value is1048576(1 MB). Set to0for unlimited size. -
CEDARLING_DATA_STORE_DEFAULT_TTL: Default TTL (Time To Live) in seconds for entries that don't specify a TTL. Default value isNone(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 is3600(1 hour). Entries with TTL exceeding this value will be rejected. Note: setting to0results 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 istrue. -
CEDARLING_DATA_STORE_MEMORY_ALERT_THRESHOLD: Memory usage threshold percentage (0.0-100.0) for triggering alerts. Default value is80.0. When capacity usage exceeds this threshold,memory_alert_triggeredwill betruein statistics.
Telemetry metrics:
CEDARLING_METRICS_COLLECTION:enabled|disabled. Whether to enable local collection of telemetry metrics, exposed via thedrain_metricsAPI.drain_metricsis 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; settingCEDARLING_LOCK_TELEMETRY_INTERVALto 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 withLockTelemetry. Default isdisabled.
HTTP client:
CEDARLING_HTTP_REQUEST_TIMEOUT: Per-request timeout in seconds. Only applicable for native targets (not WASM). Default is10(10 seconds).CEDARLING_HTTP_REQUEST_MAX_RETRIES: Maximum number of retries per request. Only network failures and the statuses408,429and5xxare retried. Any other4xx, 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 retries401, because the Lock Server refuses a client for a few seconds after registering it. Applies to native and WASM builds. Default is3.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 is3(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 to0to disable. Default is10485760(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 to0to disable; Cedarling then logs a warning at startup. Default is1000.
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. Ifenabled, the Cedarling will connect to the Lock Server for policies. Default isdisabled.CEDARLING_LOCK_SERVER_CONFIGURATION_URI: Required ifLOCK==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 usehttps, orhttponly 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. UnlessCEDARLING_LOCK_ACCESS_TOKEN_JWTis set, Cedarling registers a client at the IdP this file names and sends the client secret, and the SSA if one is set, to theregistration_endpointandtoken_endpointof 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 thetrace.writescope, see Cedarling TRACE. Takes precedence overCEDARLING_LOCK_SSA_JWT; Cedarling logs aWARNwhen both are set. Not available on WASM builds.CEDARLING_LOCK_LOG_INTERVAL: How often, in seconds, to send log messages to Lock Server.0turns transmission off. Default is0.CEDARLING_LOCK_HEALTH_INTERVAL: How often, in seconds, to send health messages to Lock Server.0turns transmission off. Default is0.CEDARLING_LOCK_TELEMETRY_INTERVAL: How often, in seconds, to send telemetry messages to Lock Server.0turns transmission off. Default is0.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, seeCEDARLING_TRACE_TRANSPORT. Default isdisabled.CEDARLING_LOCK_TRANSPORT:rest|grpc: Controls the transport protocol used to communicate with the Lock server. The gRPC transport requires compiling Cedarling with thegrpcfeature enabled. Does not affect TRACE, which has its ownCEDARLING_TRACE_TRANSPORT. Default value isrest.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 is100.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 statuses401,408,429and5xx, the matching gRPC codes (UNAUTHENTICATED,UNAVAILABLE,INTERNAL,UNKNOWN,DEADLINE_EXCEEDED,CANCELLED,ABORTED), and a gRPC reply withsuccess = falseare retried.401is retried because the Lock Server refuses a client for a few seconds after registering it, andsuccess = falsebecause 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 other4xxor 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 except401(UNAUTHENTICATED): TRACE then requests a new token and sends the request once more, and a second401is final, counted intrace.rejected. Default is5.
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 isdisabled.CEDARLING_TRACE_PRODUCER_ID: Producer id signed into every record. 1 to 255 ASCII characters: a letter or digit, then letters, digits or._:/-. Default isCEDARLING_APPLICATION_NAME, which must then follow the same rule (the defaultMy Appdoes 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 fromopenssl genpkey -algorithm ed25519 -out trace-key.pem. With TRACE enabled, this property orCEDARLING_TRACE_SIGNING_KEY_PEMis 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 whenCEDARLING_TRACE_SIGNING_KEYis 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:kidthe key is registered under in Lock Server, at most 255 characters. Default is the key thumbprint,sha256:<hex>. Cedarling logs the producer id,kidand thumbprint at startup, for registering the key.CEDARLING_TRACE_ENDPOINT:discoveredor the URL of the TRACE bulk endpoint. Default isdiscovered: thetrace_bulk_endpointof the Lock Server configuration. A blank value also meansdiscovered. The endpoint must usehttps, orhttponly tolocalhost,127.0.0.1or[::1], because requests carry the Lock access token; otherwise Cedarling logs aWARNand sends no records.CEDARLING_TRACE_TRANSPORT:rest|grpc. Protocol for sending records. Default isrest.grpcuses only the scheme, host and port ofCEDARLING_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, setCEDARLING_TRACE_ENDPOINTto it, for examplehttps://lock.example.com:50051.grpcrequires a build with thegrpcfeature.- Independent of
CEDARLING_LOCK_TRANSPORT. - Over gRPC the Lock Server certificate is always verified:
CEDARLING_LOCK_ACCEPT_INVALID_CERTSdoes not apply, and Cedarling logs aWARNwhen both are set.
CEDARLING_TRACE_BULK_MAX_RECORDS: Maximum number of records in one request. Greater than 0. Default is100, the Lock Server default. Keep it at most the Lock ServertraceConfiguration.maxBulkRecords.CEDARLING_TRACE_BULK_MAX_BYTES: Maximum size of one request in bytes. At least262146, so the largest record Lock Server accepts by default fits. Default is4194304(4 MiB), the Lock Server default. Keep it at most the Lock ServertraceConfiguration.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 theissclaim to be present in all tokens and the issuer URL must use thehttpsscheme. Loopback hosts (localhost,127.0.0.1,::1) are allowed over plain HTTP so local development is not blocked. Default isenabled. 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-configurationvia thestatus_list_endpointclaim and cache it. See the IETF Draft for more info. Default isenabled. If an issuer has nostatus_list_endpoint(including issuers with a static JWKS), the Cedarling logs a warning at startup and rejects that issuer's tokens that carry astatusclaim; tokens without one are not affected.CEDARLING_STRICT_SCHEMA_VALIDATION:enabled|disabled-- Whenenabled(default), a Cedar schema is required and policies/entities are validated against it (current behavior). Whendisabled, 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 isenabled. 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 attlclaim (per the IETFoauth-status-listspec), the effective refresh interval ismin(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 omitsttl, this value is used directly. A value of0or an unset variable resolves to the built-in default (300seconds) so the status list cannot silently go stale forever. Non-zero values below5are clamped to5. 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 whenCEDARLING_JWT_SIG_VALIDATIONisenabled.CEDARLING_JWKS_REFRESH_INTERVAL: Optional override for JWKS periodic refresh interval in seconds. When set, overrides theCache-Control: max-agefrom 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 unknownkid). Prevents abuse from invalid JWT floods triggering excessive re-fetches. Does not affect the periodic refresh schedule, which is driven byCEDARLING_JWKS_REFRESH_INTERVAL/Cache-Control: max-age. Default is30seconds.
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 is5seconds — small enough that revocation and status-list changes are picked up quickly, large enough to amortise repeated requests for the same token. Effective TTL ismin(time-until-exp, max_ttl)when both apply. Setting this to0disables 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 istrue.
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.ASYNCloader means that trusted issuers will be loaded in background. Default isSYNC. When usingASYNC, 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 bothSYNC(parallel loading during initialization) andASYNC(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 isjti. Override with any claim name (e.g.,sub,sid) if your tokens lack ajticlaim, or you need a different identifier.