Skip to content

Commit

Permalink
Merge branch 'main' into fix-location-type
Browse files Browse the repository at this point in the history
  • Loading branch information
@yuriyz
yuriyz authored Feb 5, 2025
2 parents e0673fd + 4b4d5b2 commit 51c3b28
Show file tree
Hide file tree
Showing 40 changed files with 1,163 additions and 386 deletions.
Binary file removed docs/assets/agamalab-flow-passwd-edit-cdiutil-instance.png
View file
Binary file not shown.
38 changes: 38 additions & 0 deletions docs/cedarling/cedarling-logs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,44 @@ This is set by `CEDARLING_LOG_LEVEL`
* `DEBUG`: Designates fine-grained informational events useful for debugging the application.
* `TRACE`: Provides finer-grained informational events than DEBUG. It is often used for detailed tracing of program execution.

## Memory Log interface

This interface is used to interact with the memory log storage. It provides methods for getting logs and removing them from the storage.
Same interface is translated to other languages through bindings.

Tags are used to filter logs. It can be `log_kind` and `log_level` values from log entry data.

You can obtain the `request_id` from the result structure of the `authorize` method call.

```rust
/// Log Storage
/// interface for getting log entries from the storage
pub trait LogStorage {
/// Return logs and remove them from the storage
fn pop_logs(&self) -> Vec<serde_json::Value>;

/// Get specific log entry
fn get_log_by_id(&self, id: &str) -> Option<serde_json::Value>;

/// Returns a list of all log ids
fn get_log_ids(&self) -> Vec<String>;

/// Get logs by tag, like `log_kind` or `log level`.
/// Tag can be `log_kind`, `log_level`.
fn get_logs_by_tag(&self, tag: &str) -> Vec<serde_json::Value>;

/// Get logs by request_id.
/// Return log entries that match the given request_id.
fn get_logs_by_request_id(&self, request_id: &str) -> Vec<serde_json::Value>;

/// Get log by request_id and tag, like composite key `request_id` + `log_kind`.
/// Tag can be `log_kind`, `log_level`.
/// Return log entries that match the given request_id and tag.
fn get_logs_by_request_id_and_tag(&self, request_id: &str, tag: &str)
-> Vec<serde_json::Value>;
}
```

## Jans Lock Server

In enterprise deployments, [Janssen Lock Server](../janssen-server/lock/) collects Cedarling
Expand Down
241 changes: 145 additions & 96 deletions docs/cedarling/cedarling-properties.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,9 @@ These Bootstrap Properties control default application level behavior.

**The following bootstrap properties are needed to configure log behavior:**

* **`CEDARLING_LOG_STORAGE`** : `off`, `memory`, `std_out`
* **`CEDARLING_LOG_TYPE`** : `off`, `memory`, `std_out`
* **`CEDARLING_LOG_LEVEL`** : System Log Level [See here](./cedarling-logs.md). Default to `WARN`
* **`CEDARLING_LOG_STDOUT_TYPE`** : Either `System`, `Metric`, or `Decision`. Default to System.
* **`CEDARLING_LOG_LEVEL`** : Log level filter for logging. Log level has only `System` log type entries. `TRACE` is lowest. `FATAL` is highest. Possible variants:
* FATAL
* ERROR
* WARN
* INFO
* DEBUG
* TRACE
* **`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 user entity, such as ["client_id", "rp_id", ...]
* **`CEDARLING_DECISION_LOG_DEFAULT_JWT_ID`** : Token claims that will be used for decision logging. Default is "jti", but perhaps some other claim is needed.
Expand All @@ -42,25 +35,43 @@ These Bootstrap Properties control default application level behavior.
**The following bootstrap properties are needed to configure JWT and cryptographic behavior:**

* **`CEDARLING_LOCAL_JWKS`** : JWKS file with public keys
* **`CEDARLING_LOCAL_POLICY_STORE`** : JSON object with policy store
* **`CEDARLING_POLICY_STORE_LOCAL`** : JSON object with policy store
* **`CEDARLING_POLICY_STORE_LOCAL_FN`** : Local file with JSON object with policy store
* **`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_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_TOKEN_CONFIGS`** : JSON object containing token specific configs. See: [Token Configs](#token-configs).
* **`CEDARLING_ID_TOKEN_TRUST_MODE`** : `Strict` | `None`. Varying levels of validations based on the preference of the developer.
`Strict` mode requires (1) id_token `aud` matches the access_token `client_id`; (2) if a Userinfo token is present, the `sub` matches the id_token, and that the `aud` matches the access token client_id.

**The following bootstrap properties are only needed for enterprise deployments.**

* **`CEDARLING_LOCK`** : Enabled | Disabled. If Enabled, the Cedarling will connect to the Lock Master for policies, and subscribe for SSE events.
* **`CEDARLING_LOCK_MASTER_CONFIGURATION_URI`** : Required if `LOCK` == `Enabled`. URI where Cedarling can get JSON file with all required metadata about Lock Master, i.e. `.well-known/lock-master-configuration`.
* **`CEDARLING_LOCK_DYNAMIC_CONFIGURATION`** : Enabled | Disabled, controls whether Cedarling should listen for SSE config updates.
* **`CEDARLING_LOCK`** : `enabled` | `disabled`. If `enabled`, the Cedarling will connect to the Lock Master for policies, and subscribe for SSE events.
* **`CEDARLING_LOCK_MASTER_CONFIGURATION_URI`** : Required if `LOCK` == `enabled`. URI where Cedarling can get JSON file with all required metadata about Lock Master, i.e. `.well-known/lock-master-configuration`.
* **`CEDARLING_LOCK_DYNAMIC_CONFIGURATION`** : `enabled` | `disabled`, controls whether Cedarling should listen for SSE config updates.
* **`CEDARLING_LOCK_SSA_JWT`** : SSA for DCR in a Lock Master deployment. The Cedarling will validate this SSA JWT prior to DCR.
* **`CEDARLING_LOCK_LOG_INTERVAL`** : How often to send log messages to Lock Master (0 to turn off trasmission).
* **`CEDARLING_LOCK_HEALTH_INTERVAL`** : How often to send health messages to Lock Master (0 to turn off transmission).
* **`CEDARLING_LOCK_TELEMETRY_INTERVAL`** : How often to send telemetry messages to Lock Master (0 to turn off transmission).
* **`CEDARLING_LOCK_LISTEN_SSE`** : Enabled | Disabled: controls whether Cedarling should listen for updates from the Lock Server.
* **`CEDARLING_LOCK_LISTEN_SSE`** : `enabled` | `disabled`: controls whether Cedarling should listen for updates from the Lock Server.

## Required keys for startup

* **`CEDARLING_APPLICATION_NAME`
* **`CEDARLING_TOKEN_CONFIGS` - check if default implementation of Token Config is suitable for you.

To enable usage of principals at least one of the following keys must be provided:

* **`CEDARLING_WORKLOAD_AUTHZ`
* **`CEDARLING_USER_AUTHZ`

To load policy store one of the following keys must be provided:

* **`CEDARLING_POLICY_STORE_LOCAL`
* **`CEDARLING_POLICY_STORE_URI`
* **`CEDARLING_POLICY_STORE_LOCAL_FN`

All other fields are optional and can be omitted. If a field is not provided, Cedarling will use the default value specified in the property definition.

## User-Workload Boolean Operation

Expand Down Expand Up @@ -107,6 +118,55 @@ CEDARLING_TOKEN_CONFIGS = {
}
```

## Default implementation of Token Config

Here is rust code default implementation of Token Configs (`CEDARLING_TOKEN_CONFIGS`). This is used when no custom token config is provided.

```rust
impl Default for TokenConfigs {
fn default() -> Self {
Self(HashMap::from([
("access_token".to_string(), TokenConfig {
entity_type_name: "Access_token".to_string(),
claims: ClaimsValidationConfig {
iss: FeatureToggle::Enabled,
sub: FeatureToggle::Disabled,
aud: FeatureToggle::Disabled,
exp: FeatureToggle::Enabled,
nbf: FeatureToggle::Disabled,
iat: FeatureToggle::Disabled,
jti: FeatureToggle::Enabled,
},
}),
("id_token".to_string(), TokenConfig {
entity_type_name: "id_token".to_string(),
claims: ClaimsValidationConfig {
iss: FeatureToggle::Enabled,
sub: FeatureToggle::Enabled,
aud: FeatureToggle::Enabled,
exp: FeatureToggle::Enabled,
nbf: FeatureToggle::Disabled,
iat: FeatureToggle::Disabled,
jti: FeatureToggle::Disabled,
},
}),
("userinfo_token".to_string(), TokenConfig {
entity_type_name: "Userinfo_token".to_string(),
claims: ClaimsValidationConfig {
iss: FeatureToggle::Enabled,
sub: FeatureToggle::Enabled,
aud: FeatureToggle::Enabled,
exp: FeatureToggle::Enabled,
nbf: FeatureToggle::Disabled,
iat: FeatureToggle::Disabled,
jti: FeatureToggle::Disabled,
},
}),
]))
}
}
```

## ID Token Trust Mode

The level of validation for the ID Token JWT can be set to either `None` or `Strict`.
Expand Down Expand Up @@ -165,59 +225,50 @@ Below is an example of a bootstrap config in JSON format. Not all fields should

```json
{
"CEDARLING_APPLICATION_NAME": "My App",
"CEDARLING_POLICY_STORE_URI": "",
"CEDARLING_POLICY_STORE_ID": "840da5d85403f35ea76519ed1a18a33989f855bf1cf8",
"CEDARLING_LOG_TYPE": "memory",
"CEDARLING_LOG_LEVEL": "INFO",
"CEDARLING_DECISION_LOG_USER_CLAIMS": ["sub", "email", "username"],
"CEDARLING_DECISION_LOG_WORKLOAD_CLAIMS": ["client_id", "rp_id"],
"CEDARLING_DECISION_LOG_DEFAULT_JWT_ID": "jti",
"CEDARLING_LOG_TTL": 60,
"CEDARLING_USER_AUTHZ": "enabled",
"CEDARLING_WORKLOAD_AUTHZ": "enabled",
"CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION": "AND",
"CEDARLING_MAPPING_USER": "CustomUser",
"CEDARLING_MAPPING_WORKLOAD": "CustomWorkload",
"CEDARLING_MAPPING_ROLE": "CustomRole",
"CEDARLING_LOCAL_JWKS": "../test_files/local_jwks.json",
"CEDARLING_LOCAL_POLICY_STORE": null,
"CEDARLING_POLICY_STORE_LOCAL_FN": "../test_files/policy-store_blobby.json",
"CEDARLING_JWT_SIG_VALIDATION": "enabled",
"CEDARLING_JWT_STATUS_VALIDATION": "disabled",
"CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [
"HS256",
"RS256"
],
"CEDARLING_TOKEN_CONFIGS": {
"access_token": {
"entity_type_name": "Access_token",
"exp": "enabled",
},
"id_token": {
"entity_type_name": "id_token",
"iss": "enabled",
"sub": "enabled",
"exp": "enabled",
"iat": "enabled",
"aud": "enabled",
},
"id_token": {
"entity_type_name": "id_token",
"iss": "enabled",
"aud": "enabled",
"sub": "enabled",
"exp": "enabled",
},
"CEDARLING_APPLICATION_NAME": "My App",
"CEDARLING_USER_AUTHZ": "enabled",
"CEDARLING_WORKLOAD_AUTHZ": "enabled",
"CEDARLING_POLICY_STORE_URI": null,
"CEDARLING_POLICY_STORE_LOCAL": null,
"CEDARLING_POLICY_STORE_LOCAL_FN": "./example_files/policy-store.json",
"CEDARLING_TOKEN_CONFIGS": {
"access_token": {
"entity_type_name": "Access_token"
},
"id_token": {
"entity_type_name": "id_token"
},
"CEDARLING_ID_TOKEN_TRUST_MODE": "Strict",
"CEDARLING_LOCK": "disabled",
"CEDARLING_LOCK_MASTER_CONFIGURATION_URI": null,
"CEDARLING_DYNAMIC_CONFIGURATION": "disabled",
"CEDARLING_LOCK_SSA_JWT": null,
"CEDARLING_AUDIT_HEALTH_INTERVAL": 0,
"CEDARLING_AUDIT_TELEMETRY_INTERVAL": 0,
"CEDARLING_LISTEN_SSE": "disabled"
"userinfo_token": {
"entity_type_name": "Userinfo_token"
}
},
"CEDARLING_POLICY_STORE_ID": "gICAgcHJpbmNpcGFsIGlz",
"CEDARLING_LOG_TYPE": "std_out",
"CEDARLING_LOG_LEVEL": "INFO",
"CEDARLING_LOG_TTL": null,
"CEDARLING_DECISION_LOG_USER_CLAIMS": [
"sub",
"email"
],
"CEDARLING_DECISION_LOG_WORKLOAD_CLAIMS": [
"client_id",
"rp_id"
],
"CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION": "AND",
"CEDARLING_LOCAL_JWKS": null,
"CEDARLING_JWT_SIG_VALIDATION": "disabled",
"CEDARLING_JWT_STATUS_VALIDATION": "disabled",
"CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [
"HS256",
"RS256"
],
"CEDARLING_ID_TOKEN_TRUST_MODE": "strict",
"CEDARLING_LOCK": "disabled",
"CEDARLING_LOCK_MASTER_CONFIGURATION_URI": null,
"CEDARLING_LOCK_DYNAMIC_CONFIGURATION": "disabled",
"CEDARLING_LOCK_HEALTH_INTERVAL": 0,
"CEDARLING_LOCK_TELEMETRY_INTERVAL": 0,
"CEDARLING_LOCK_LISTEN_SSE": "disabled"
}
```

Expand Down Expand Up @@ -246,39 +297,37 @@ Below is an example of a bootstrap config in YAML format. Not all fields should

```yaml
CEDARLING_APPLICATION_NAME: My App
CEDARLING_POLICY_STORE_URI: ''
CEDARLING_POLICY_STORE_ID: '840da5d85403f35ea76519ed1a18a33989f855bf1cf8'
CEDARLING_LOG_TYPE: 'memory'
CEDARLING_LOG_LEVEL: 'INFO'
CEDARLING_USER_AUTHZ: enabled
CEDARLING_WORKLOAD_AUTHZ: enabled
CEDARLING_POLICY_STORE_URI: null
CEDARLING_POLICY_STORE_LOCAL: null
CEDARLING_POLICY_STORE_LOCAL_FN: ./example_files/policy-store.json
CEDARLING_TOKEN_CONFIGS:
access_token: { entity_type_name: "Access_token" }
id_token: { entity_type_name: "id_token" }
userinfo_token: { entity_type_name: "Userinfo_token" }

CEDARLING_POLICY_STORE_ID: gICAgcHJpbmNpcGFsIGlz
CEDARLING_LOG_TYPE: std_out
CEDARLING_LOG_LEVEL: INFO
CEDARLING_LOG_TTL: null
CEDARLING_DECISION_LOG_USER_CLAIMS: ["sub","email"]
CEDARLING_DECISION_LOG_WORKLOAD_CLAIMS: ["client_id", "rp_id"]
CEDARLING_LOG_TTL: 60
CEDARLING_USER_AUTHZ: 'enabled'
CEDARLING_WORKLOAD_AUTHZ: 'enabled'
CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION: 'AND'
CEDARLING_MAPPING_USER: 'CustomUser'
CEDARLING_MAPPING_WORKLOAD: 'CustomWorkload'
CEDARLING_MAPPING_ROLE: 'CustomRole'
CEDARLING_LOCAL_JWKS: '../test_files/local_jwks.json'
CEDARLING_LOCAL_POLICY_STORE: null
CEDARLING_POLICY_STORE_LOCAL_FN: '../test_files/policy-store_blobby.json'
CEDARLING_JWT_SIG_VALIDATION: 'enabled'
CEDARLING_JWT_STATUS_VALIDATION: 'disabled'
CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION: AND
CEDARLING_LOCAL_JWKS: null
CEDARLING_JWT_SIG_VALIDATION: disabled
CEDARLING_JWT_STATUS_VALIDATION: disabled
CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED:
- 'HS256'
- 'RS256'
CEDARLING_TOKENS_CONFIG:
access_token: CustomAccessToken
id_token: CustomIdToken
userinfo_token: CustomUserinfoToken
CEDARLING_ID_TOKEN_TRUST_MODE: 'Strict'
CEDARLING_LOCK: 'disabled'
- HS256
- RS256

CEDARLING_ID_TOKEN_TRUST_MODE: strict
CEDARLING_LOCK: disabled
CEDARLING_LOCK_MASTER_CONFIGURATION_URI: null
CEDARLING_DYNAMIC_CONFIGURATION: 'disabled'
CEDARLING_LOCK_SSA_JWT: 0
CEDARLING_AUDIT_HEALTH_INTERVAL: 0
CEDARLING_AUDIT_TELEMETRY_INTERVAL: 0
CEDARLING_LISTEN_SSE: 'disabled'
CEDARLING_LOCK_DYNAMIC_CONFIGURATION: disabled
CEDARLING_LOCK_HEALTH_INTERVAL: 0
CEDARLING_LOCK_TELEMETRY_INTERVAL: 0
CEDARLING_LOCK_LISTEN_SSE: disabled
```
* Note that properties set to `'disabled'`, an empty string `''`, zero `0`, and `null` can be ommited since they are the defaults.
Loading

0 comments on commit 51c3b28

Please sign in to comment.