feat (jans-cedarling): Load trusted issuers on startup on the background

docs/cedarling/reference/cedarling-properties.md

@@ -18,9 +18,9 @@ These Bootstrap Properties control default application level behavior.
 
 To enable usage of principals at least one of the following keys must be provided:
 
-- **`CEDARLING_WORKLOAD_AUTHZ`** : When `enabled`, Cedar engine authorization is queried for a Workload principal.
+- **`CEDARLING_WORKLOAD_AUTHZ`** : When `enabled`, Cedar engine authorization is queried for a Workload principal. Default is `disabled`.
 
-- **`CEDARLING_USER_AUTHZ`** : When `enabled`, Cedar engine authorization is queried for a User principal.
+- **`CEDARLING_USER_AUTHZ`** : When `enabled`, Cedar engine authorization is queried for a User principal. Default is `disabled`.
 
 To load policy store one of the following keys must be provided:
 
@@ -58,6 +58,10 @@ All other fields are optional and can be omitted. If a field is not provided, Ce
 
 - **`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`.
 
+- **`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`.
+
+- **`CEDARLING_TRUSTED_ISSUER_LOADER_WORKERS`** : Number of concurrent workers used to asynchronously load trusted issuers. Default value is 1. Zero will be treated as default value.
+
 **Cedar Entity Mapping properties**
 
 - **`CEDARLING_MAPPING_USER`** : Name of Cedar User schema entity if we don't want to use default. When specified Cedarling try build defined entity (from schema) as user instead of default `User` entity defined in `cedar` schema. Works in namespace defined in the policy store. Default value: `Jans::User`.
@@ -68,7 +72,7 @@ All other fields are optional and can be omitted. If a field is not provided, Ce
 
 **The following bootstrap properties are needed to configure log behavior:**
 
-- **`CEDARLING_LOG_TYPE`** : `off`, `memory`, `std_out`
+- **`CEDARLING_LOG_TYPE`** : `off`, `memory`, `std_out`. Default is `off`.
 - **`CEDARLING_LOG_LEVEL`** : System Log Level [See here](./cedarling-logs.md). Default to `WARN`
 - **`CEDARLING_DECISION_LOG_USER_CLAIMS`** : List of claims to map from user entity, such as ["sub", "email", "username", ...]
 - **`CEDARLING_DECISION_LOG_WORKLOAD_CLAIMS`** : List of claims to map from workload entity, such as ["client_id", "rp_id", ...]
@@ -84,9 +88,9 @@ All other fields are optional and can be omitted. If a field is not provided, Ce
 
 - **`CEDARLING_LOCAL_JWKS`** : Path to a local file containing a JWKS
 
-- **`CEDARLING_JWT_SIG_VALIDATION`** : `enabled` | `disabled` -- Whether to check the signature of all JWT tokens. This requires an `iss` is present.
-- **`CEDARLING_JWT_STATUS_VALIDATION`** : `enabled` | `disabled` -- Whether to check the status of the JWT. On startup, the Cedarling should fetch and retreive the latest Status List JWT from the `.well-known/openid-configuration` via the `status_list_endpoint` claim and cache it. See the [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/) for more info.
-- **`CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED`** : Only tokens signed with these algorithms are acceptable to the Cedarling.
+- **`CEDARLING_JWT_SIG_VALIDATION`** : `enabled` | `disabled` -- Whether to check the signature of all JWT tokens. This requires an `iss` is present. Default is `disabled`.
+- **`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](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/) for more info. Default is `disabled`.
+- **`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_ID_TOKEN_TRUST_MODE`** : `strict` | `never` | `always` | `ifpresent`. Varying levels of validations based on the preference of the developer.
 
   - **`strict`** (default): Enforces strict validation rules:
@@ -103,12 +107,12 @@ All other fields are optional and can be omitted. If a field is not provided, Ce
 
 **The following bootstrap properties are only needed for the Lock Server Integration.**
 
-- **`CEDARLING_LOCK`** : `enabled` | `disabled`. If `enabled`, the Cedarling will connect to the Lock Server for policies, and subscribe for SSE events.
+- **`CEDARLING_LOCK`** : `enabled` | `disabled`. If `enabled`, the Cedarling will connect to the Lock Server for policies, and subscribe for SSE events. 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-master-configuration`.
-- **`CEDARLING_LOCK_DYNAMIC_CONFIGURATION`** : `enabled` | `disabled`, controls whether Cedarling should listen for SSE config updates.
+- **`CEDARLING_LOCK_DYNAMIC_CONFIGURATION`** : `enabled` | `disabled`, controls whether Cedarling should listen for SSE config updates. Default is `disabled`.
 - **`CEDARLING_LOCK_SSA_JWT`** : SSA for DCR in a Lock Server deployment. The Cedarling will validate this SSA JWT prior to DCR.
 - **`CEDARLING_LOCK_LOG_INTERVAL`** : How often to send log messages to Lock Server (0 to turn off transmission).
 - **`CEDARLING_LOCK_HEALTH_INTERVAL`** : How often to send health messages to Lock Server (0 to turn off transmission).
 - **`CEDARLING_LOCK_TELEMETRY_INTERVAL`** : How often to send telemetry messages to Lock Server (0 to turn off transmission).
-- **`CEDARLING_LOCK_LISTEN_SSE`** : `enabled` | `disabled`: controls whether Cedarling should listen for updates from the Lock Server.
-- **`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.
+- **`CEDARLING_LOCK_LISTEN_SSE`** : `enabled` | `disabled`: controls whether Cedarling should listen for updates from the Lock Server. Default is `disabled`.
+- **`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. Default is `disabled`.

jans-cedarling/AGENTS.md

@@ -79,9 +79,11 @@
 - Use test_utils crate for shared test helpers
 - Follow existing test patterns in authorize_*.rs files
 - Include both positive and negative test cases
-- For error checking, use `assert!(matches!(...), "explicit comment")` instead of `assert!(result.is_err())`
-- Use `expect_err("explicit comment")` instead of `panic()`
-- Always include explicit comments explaining what error is expected
+- For success checking, use `result.expect("descriptive message")` instead of `assert!(result.is_ok())`
+- For error checking, use `result.expect_err("descriptive message")` instead of `assert!(result.is_err())`
+- For pattern matching errors, use `assert!(matches!(...), "descriptive message")`
+- All assertions must include a descriptive message explaining what is being tested
+- Use `expect_err("explicit comment")` instead of `panic()` when expecting errors
 
 **File Headers:**
 - Each Rust file must contain the Apache 2.0 license header:

jans-cedarling/cedarling/Cargo.toml

@@ -46,7 +46,10 @@ async-trait = "0.1.88"
 futures = "0.3.31"
 wasm-bindgen-futures = { workspace = true }
 config = "0.15.11"
-ahash = { version = "0.8.12", default-features = false, features = ["no-rng"] }
+ahash = { version = "0.8.12", default-features = false, features = [
+    "no-rng",
+    "std",
+] }
 vfs = "0.12"
 hex = "0.4.3"
 sha2 = "0.10.8"

jans-cedarling/cedarling/src/bootstrap_config/decode.rs

@@ -10,6 +10,7 @@ use std::collections::{HashMap, HashSet};
 use std::env;
 use std::fmt::Display;
 use std::fs;
+use std::num::NonZeroUsize;
 use std::path::Path;
 use std::str::FromStr;
 
@@ -20,6 +21,7 @@ use super::{
     MemoryLogConfig, PolicyStoreConfig, PolicyStoreSource,
 };
 use super::{BootstrapConfigRaw, LockServiceConfig};
+use crate::jwt_config::{TrustedIssuerLoaderConfig, TrustedIssuerLoaderTypeRaw};
 use crate::log::{LogLevel, StdOutLoggerMode};
 use jsonwebtoken::Algorithm;
 use serde::{Deserialize, Deserializer, Serialize};
@@ -112,6 +114,9 @@ impl BootstrapConfig {
             })
             .transpose()?;
 
+        let trusted_issuer_workers = NonZeroUsize::new(raw.trusted_issuer_loader_workers)
+            .unwrap_or_else(|| unsafe { NonZeroUsize::new_unchecked(1) });
+
         // JWT Config
         let jwt_config = JwtConfig {
             jwks,
@@ -121,6 +126,9 @@ impl BootstrapConfig {
             token_cache_max_ttl_secs: raw.token_cache_max_ttl,
             token_cache_capacity: raw.token_cache_capacity,
             token_cache_earliest_expiration_eviction: raw.token_cache_earliest_expiration_eviction,
+            trusted_issuer_loader: raw
+                .trusted_issuer_loader_type
+                .to_config(trusted_issuer_workers),
         };
 
         let authorization_config = AuthorizationConfig {

jans-cedarling/cedarling/src/bootstrap_config/jwt_config.rs

@@ -6,7 +6,7 @@
 
 use jsonwebtoken::Algorithm;
 use serde::{Deserialize, Serialize};
-use std::collections::HashSet;
+use std::{collections::HashSet, num::NonZeroUsize};
 
 /// The set of Bootstrap properties related to JWT validation.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -52,6 +52,8 @@ pub struct JwtConfig {
     /// When the cache reaches its capacity, the entry with the nearest
     /// expiration timestamp will be removed to make room for a new one.
     pub token_cache_earliest_expiration_eviction: bool,
+    /// Configuration for loading trusted issuers.
+    pub trusted_issuer_loader: TrustedIssuerLoaderConfig,
 }
 
 /// Validation options related to JSON Web Tokens (JWT).
@@ -182,6 +184,7 @@ impl Default for JwtConfig {
             token_cache_capacity: 100,
             token_cache_earliest_expiration_eviction: true,
             token_cache_max_ttl_secs: 60 * 5, // 5min
+            trusted_issuer_loader: TrustedIssuerLoaderConfig::default(),
         }
     }
 }
@@ -220,3 +223,60 @@ impl JwtConfig {
         self
     }
 }
+
+/// Raw representation of trusted issuer loader type from environment variable.
+/// Is used in [`BootstrapConfigRaw`].
+#[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize)]
+pub enum TrustedIssuerLoaderTypeRaw {
+    /// Synchronous loading
+    #[default]
+    #[serde(rename = "SYNC")]
+    Sync,
+    /// Asynchronous loading
+    #[serde(rename = "ASYNC")]
+    Async,
+}
+
+impl TrustedIssuerLoaderTypeRaw {
+    /// Converts raw representation to `TrustedIssuerLoaderConfig`.
+    pub(crate) fn to_config(&self, workers: NonZeroUsize) -> TrustedIssuerLoaderConfig {
+        match self {
+            TrustedIssuerLoaderTypeRaw::Sync => TrustedIssuerLoaderConfig::Sync { workers },
+            TrustedIssuerLoaderTypeRaw::Async => TrustedIssuerLoaderConfig::Async { workers },
+        }
+    }
+}
+
+/// Config structure that define how trusted issuers will be loaded.
+///
+/// Default is `Sync` with 1 worker.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum TrustedIssuerLoaderConfig {
+    /// Synchronous loading, on start program.
+    /// The Cedarling will load all entities on start in "blocking mode" (you need to wait).
+    Sync {
+        /// Workers count
+        workers: NonZeroUsize,
+    },
+    /// Asynchronous loading, on start program.
+    /// The Cedarling will load all entities on the background.
+    /// You need specify workers count.
+    Async {
+        /// Workers count
+        workers: NonZeroUsize,
+    },
+}
+
+impl TrustedIssuerLoaderConfig {
+    pub(crate) fn is_sync(&self) -> bool {
+        matches!(self, TrustedIssuerLoaderConfig::Sync { .. })
+    }
+}
+
+impl Default for TrustedIssuerLoaderConfig {
+    fn default() -> Self {
+        Self::Sync {
+            workers: NonZeroUsize::new(1).unwrap(),
+        }
+    }
+}

jans-cedarling/cedarling/src/bootstrap_config/raw_config/config.rs

@@ -14,6 +14,7 @@ use super::feature_types::{FeatureToggle, LoggerType};
 use super::json_util::{deserialize_or_parse_string_as_json, parse_option_string};
 use crate::UnsignedRoleIdSrc;
 use crate::common::json_rules::JsonRule;
+use crate::jwt_config::TrustedIssuerLoaderTypeRaw;
 use crate::log::LogLevel;
 use jsonwebtoken::Algorithm;
 use serde::{Deserialize, Serialize};
@@ -305,6 +306,27 @@ pub struct BootstrapConfigRaw {
         default = "default_true"
     )]
     pub token_cache_earliest_expiration_eviction: bool,
+    /// Type of trusted issuer loader.
+    /// If not set, synchronous loader is used.
+    /// Can be `SYNC` or `ASYNC`.
+    ///
+    /// Sync loader means that trusted issuers will be loaded on initialization.
+    /// Async loader means that trusted issuers will be loaded in background.
+    #[serde(
+        rename = "CEDARLING_TRUSTED_ISSUER_LOADER_TYPE",
+        default,
+        deserialize_with = "deserialize_or_parse_string_as_json"
+    )]
+    pub trusted_issuer_loader_type: TrustedIssuerLoaderTypeRaw,
+    /// Number of concurrent workers used to asynchronously load trusted issuers.
+    /// Default value is 1.
+    /// Zero will be treated as default value.
+    #[serde(
+        rename = "CEDARLING_TRUSTED_ISSUER_LOADER_WORKERS",
+        default,
+        deserialize_with = "deserialize_or_parse_string_as_json"
+    )]
+    pub trusted_issuer_loader_workers: usize,
 }
 
 impl Default for BootstrapConfigRaw {

jans-cedarling/cedarling/src/common/issuer_utils.rs

@@ -3,10 +3,73 @@
 //
 // Copyright (c) 2024, Gluu, Inc.
 
+use std::fmt;
+
+use serde::Serialize;
+use serde::de::{self, Deserialize, Deserializer, Visitor};
+
+/// Utility structure that holds a normalized issuer string
+#[derive(Debug, Clone, PartialEq, Eq, Hash, derive_more::Display)]
+pub(crate) struct IssClaim(String);
+
+impl IssClaim {
+    /// Create a new Issuer with normalized value
+    pub(crate) fn new(issuer: &str) -> Self {
+        Self(normalize_issuer(issuer))
+    }
+
+    /// Get the issuer as a &str
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl<'de> Deserialize<'de> for IssClaim {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        struct IssClaimVisitor;
+
+        impl Visitor<'_> for IssClaimVisitor {
+            type Value = IssClaim;
+
+            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+                formatter.write_str("a string representing an issuer claim")
+            }
+
+            fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
+            where
+                E: de::Error,
+            {
+                Ok(IssClaim::new(value))
+            }
+
+            fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
+            where
+                E: de::Error,
+            {
+                Ok(IssClaim::new(&value))
+            }
+        }
+
+        deserializer.deserialize_string(IssClaimVisitor)
+    }
+}
+
+impl Serialize for IssClaim {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.0)
+    }
+}
+
 /// Normalizes an issuer URL by removing trailing slashes
 /// This handles cases where IDPs like Auth0 return issuers with trailing slashes
 /// but the policy store configuration might not have them
-pub(crate) fn normalize_issuer(issuer: &str) -> String {
+fn normalize_issuer(issuer: &str) -> String {
     // Parse the issuer as a URL be consistent after parsing trusted issuers URL by `url` crate.
     if let Ok(url) = url::Url::parse(issuer) {
         url.to_string().trim_end_matches('/').to_string()