Skip to content

Cedarling: Design for `default_entities` support in Policy Store

Jump to bottom
Michael Schwartz edited this page Aug 27, 2025 · 1 revision

Requirements Document

Introduction

This feature adds support for default_entities in the policy store specification, enabling applications to define static entities that are loaded by the Cedarling on startup. This addresses the common need for organizational data, role-capability mappings, and other static reference information that policies can reference during authorization decisions.

The feature extends the existing policy store format to include a new default_entities section containing base64-encoded entity data with unique identifiers, making it easier to manage static application context without requiring dynamic token-based entity creation.

Requirements

Requirement 1

User Story: As a policy administrator, I want to define static entities in the policy store, so that I can reference organizational data and capability mappings in my authorization policies without requiring dynamic entity creation.

Acceptance Criteria

  1. WHEN a policy store is created THEN the system SHALL support an optional default_entities field in the policy store JSON structure
  2. WHEN default_entities are defined THEN each entity SHALL have a unique identifier as the key
  3. WHEN default_entities are defined THEN each entity value SHALL be base64-encoded entity JSON content
  4. WHEN a policy store contains default_entities THEN the structure SHALL follow the format: "default_entities": {"entity_id": "base64-content", ...}

Requirement 2

User Story: As a Cedarling runtime, I want to automatically load default entities on startup, so that they are available for policy evaluation without additional configuration steps.

Acceptance Criteria

  1. WHEN the Cedarling starts up THEN it SHALL automatically load all entities from the default_entities section of the policy store
  2. WHEN loading default entities THEN the Cedarling SHALL decode the base64 content and parse it as valid Cedar entity JSON
  3. WHEN default entities are loaded THEN they SHALL be available in the entity store for policy evaluation
  4. IF the default_entities section is missing THEN the Cedarling SHALL continue normal operation without error
  5. IF a default entity fails to load THEN the Cedarling SHALL log an error and continue loading other entities

Requirement 3

User Story: As a policy author, I want to reference default entities in my policies, so that I can create authorization rules based on static organizational data and capability mappings.

Acceptance Criteria

  1. WHEN writing policies THEN authors SHALL be able to reference default entities using standard Cedar entity syntax
  2. WHEN a policy references a default entity THEN the entity SHALL be available during policy evaluation
  3. WHEN policies use default entities THEN they SHALL support attribute access and parent relationship traversal
  4. WHEN default entities have parent relationships THEN the policy engine SHALL correctly resolve hierarchical queries

Requirement 4

User Story: As a system integrator, I want default entities to support complex data structures, so that I can model organizational hierarchies, product catalogs, and role-capability mappings effectively.

Acceptance Criteria

  1. WHEN defining default entities THEN they SHALL support all standard Cedar entity attributes including strings, numbers, booleans, and sets
  2. WHEN defining default entities THEN they SHALL support parent-child relationships through the parents field
  3. WHEN defining default entities THEN they SHALL support custom attributes relevant to the application domain
  4. WHEN default entities contain nested data THEN the policy engine SHALL correctly access nested attributes in policy conditions

Requirement 5

User Story: As a policy store administrator, I want default entities to be versioned with the policy store, so that entity changes are tracked and can be reviewed alongside policy changes.

Acceptance Criteria

  1. WHEN a policy store is updated THEN changes to default_entities SHALL be included in the policy store version
  2. WHEN reviewing policy store changes THEN administrators SHALL be able to see modifications to default entities
  3. WHEN deploying policy stores THEN default entities SHALL be deployed atomically with policies and schema
  4. WHEN rolling back policy stores THEN default entities SHALL be rolled back to the previous version

Requirement 6

User Story: As a security administrator, I want default entities to be validated against the schema, so that I can ensure data integrity and prevent runtime errors.

Acceptance Criteria

  1. WHEN default entities are loaded THEN they SHALL be validated against the Cedar schema if present
  2. WHEN a default entity violates the schema THEN the system SHALL reject the entity and log a validation error
  3. WHEN entity types in default entities are referenced THEN they SHALL match entity types defined in the schema
  4. WHEN default entities have attributes THEN the attributes SHALL conform to the schema attribute definitions

Design Document

Overview

The default_entities feature extends the Cedar policy store specification to support static entity definitions that are loaded by the Cedarling at startup. This design addresses the need for applications to reference organizational data, role-capability mappings, and other static context in authorization policies without requiring dynamic entity creation from tokens.

The feature introduces a new optional default_entities section in the policy store JSON format, where entities are stored as base64-encoded JSON with unique identifiers. The Cedarling will automatically decode and load these entities into its entity store during initialization, making them available for policy evaluation.

Architecture

Policy Store Structure Extension

The existing policy store format will be extended to include an optional default_entities field:

{
  "cedar_version": "4.4.0",
  "policy_stores": {
    "store_id": {
      "name": "Application Policy Store",
      "description": "Policy store with default entities",
      "policies": {
        "policy_id": "base64-encoded-policy-content"
      },
      "trusted_issuers": {
        "issuer_config": "..."
      },
      "schema": "base64-encoded-schema-content",
      "default_entities": {
        "entity_uuid_1": "base64-encoded-entity-json",
        "entity_uuid_2": "base64-encoded-entity-json"
      }
    }
  }
}

Entity Storage Format

Each default entity is stored with a unique identifier (UUID) as the key and base64-encoded entity JSON as the value. The decoded entity JSON follows the standard Cedar entity format:

{
  "uid": { "type": "EntityType", "id": "entity_id" },
  "attrs": {
    "attribute_name": "attribute_value",
    "nested_attr": {
      "sub_attr": "value"
    }
  },
  "parents": [
    { "type": "ParentType", "id": "parent_id" }
  ]
}

Cedarling Integration

The Cedarling will be enhanced with a new component responsible for loading default entities during startup:

graph TD
    A[Cedarling Startup] --> B[Load Policy Store]
    B --> C{Default Entities Present?}
    C -->|Yes| D[Decode Base64 Content]
    C -->|No| H[Continue Normal Startup]
    D --> E[Parse Entity JSON]
    E --> F[Validate Against Schema]
    F --> G[Load into Entity Store]
    G --> H[Continue Normal Startup]
    
    E -->|Parse Error| I[Log Error & Skip Entity]
    F -->|Validation Error| I
    I --> J{More Entities?}
    J -->|Yes| D
    J -->|No| H
Loading

Components and Interfaces

1. Policy Store Parser Enhancement

Interface: PolicyStoreParser

public interface PolicyStoreParser {
    PolicyStore parse(String policyStoreJson) throws PolicyStoreParseException;
    
    // New method for default entities
    Map<String, DefaultEntity> parseDefaultEntities(JsonNode defaultEntitiesNode) 
        throws DefaultEntityParseException;
}

Responsibilities:

  • Parse the default_entities section from policy store JSON
  • Decode base64-encoded entity content
  • Convert JSON to internal entity representation
  • Handle parsing errors gracefully

2. Default Entity Loader

Interface: DefaultEntityLoader

public interface DefaultEntityLoader {
    void loadDefaultEntities(Map<String, DefaultEntity> entities, EntityStore entityStore)
        throws EntityLoadException;
    
    boolean validateEntity(DefaultEntity entity, Schema schema);
    
    void logLoadingResults(LoadingResults results);
}

Responsibilities:

  • Load parsed default entities into the Cedarling entity store
  • Validate entities against the Cedar schema
  • Handle loading errors and continue with remaining entities
  • Provide detailed logging for troubleshooting

3. Entity Store Integration

Interface: EntityStore (Enhanced)

public interface EntityStore {
    // Existing methods...
    
    // New methods for default entities
    void addDefaultEntity(String entityId, Entity entity) throws EntityStoreException;
    
    void addDefaultEntities(Map<String, Entity> entities) throws EntityStoreException;
    
    boolean hasDefaultEntity(String entityId);
    
    Set<String> getDefaultEntityIds();
}

Responsibilities:

  • Store default entities separately from runtime entities
  • Provide efficient lookup for policy evaluation
  • Support entity hierarchy traversal
  • Maintain entity relationships and attributes

Data Models

DefaultEntity Model

public class DefaultEntity {
    private final String id;
    private final EntityUid uid;
    private final Map<String, AttributeValue> attributes;
    private final Set<EntityUid> parents;
    private final String originalJson;
    
    // Constructor, getters, validation methods
}

LoadingResults Model

public class LoadingResults {
    private final int totalEntities;
    private final int successfullyLoaded;
    private final int failed;
    private final List<LoadingError> errors;
    
    // Methods for reporting and logging
}

Configuration Model

public class DefaultEntityConfig {
    private final boolean enabled;
    private final boolean strictValidation;
    private final boolean failOnError;
    private final int maxEntities;
    
    // Configuration for default entity behavior
}

Error Handling

Error Categories

  1. Parse Errors

    • Invalid base64 encoding
    • Malformed JSON structure
    • Missing required fields

  2. Validation Errors

    • Schema validation failures
    • Invalid entity type references
    • Circular parent relationships

  3. Loading Errors

    • Entity store capacity limits
    • Duplicate entity IDs
    • System resource constraints

Error Recovery Strategy

  • Graceful Degradation: Continue loading other entities when one fails
  • Detailed Logging: Log specific error details for troubleshooting
  • Configuration Options: Allow strict vs. lenient validation modes
  • Startup Behavior: Never fail Cedarling startup due to default entity errors

Testing Strategy

Unit Testing

  1. Policy Store Parser Tests

    • Valid default entities parsing
    • Invalid JSON handling
    • Base64 decoding edge cases
    • Empty default entities section

  2. Entity Loader Tests

    • Successful entity loading
    • Schema validation scenarios
    • Error handling and recovery
    • Performance with large entity sets

  3. Entity Store Integration Tests

    • Entity storage and retrieval
    • Parent relationship resolution
    • Attribute access patterns
    • Memory usage optimization

Integration Testing

  1. End-to-End Policy Evaluation

    • Policies referencing default entities
    • Complex entity hierarchies
    • Attribute-based authorization
    • Performance under load

  2. Schema Compatibility Testing

    • Entity validation against various schemas
    • Schema evolution scenarios
    • Backward compatibility verification

Performance Testing

  1. Startup Performance

    • Loading time with various entity counts
    • Memory usage patterns
    • Concurrent loading scenarios

  2. Runtime Performance

    • Policy evaluation with default entities
    • Entity lookup performance
    • Memory footprint analysis

Security Considerations

Data Integrity

  • Base64 Encoding: Ensures safe transport and storage of entity data
  • Schema Validation: Prevents malformed entities from affecting policy evaluation
  • Input Sanitization: Validate all entity attributes and relationships

Access Control

  • Policy Store Security: Default entities inherit policy store access controls
  • Entity Visibility: Default entities are available to all policies in the store
  • Audit Trail: Log all default entity loading activities

Resource Protection

  • Memory Limits: Implement configurable limits on entity count and size
  • Loading Timeouts: Prevent indefinite loading operations
  • Error Boundaries: Isolate default entity failures from core Cedarling functionality

Migration and Compatibility

Backward Compatibility

  • Optional Feature: default_entities section is completely optional
  • Existing Behavior: No changes to current policy store functionality
  • Version Support: Compatible with existing Cedar versions

Migration Path

  1. Phase 1: Add default_entities support to policy store parser
  2. Phase 2: Implement entity loading in Cedarling
  3. Phase 3: Enable schema validation for default entities
  4. Phase 4: Add management tools and utilities

Deployment Strategy

  • Feature Flags: Allow enabling/disabling default entity support
  • Gradual Rollout: Deploy to test environments first
  • Monitoring: Track loading performance and error rates
  • Rollback Plan: Ability to disable feature if issues arise

Implementation Plan

  • 1. Create core data models and interfaces

    • Define DefaultEntity, LoadingResults, and DefaultEntityConfig data models
    • Create PolicyStoreParser interface with default entities parsing methods
    • Create DefaultEntityLoader interface for entity loading operations
    • Extend EntityStore interface to support default entity storage
    • Requirements: 1.1, 1.2, 1.3, 1.4

  • 2. Implement policy store parser enhancements

    • Add parseDefaultEntities method to handle base64 decoding and JSON parsing
    • Implement error handling for malformed JSON and invalid base64 content
    • Create unit tests for parsing valid and invalid default entities sections
    • Add validation for entity JSON structure and required fields
    • Requirements: 1.1, 1.2, 1.3, 2.2, 6.1

  • 3. Develop default entity loader component

    • Implement DefaultEntityLoader with entity validation against Cedar schema
    • Create entity loading logic that handles errors gracefully and continues processing
    • Add detailed logging for successful loads, validation failures, and parse errors
    • Implement configuration options for strict vs lenient validation modes
    • Requirements: 2.1, 2.4, 2.5, 6.2, 6.3

  • 4. Enhance entity store for default entity support

    • Extend EntityStore implementation to store default entities separately from runtime entities
    • Implement efficient lookup methods for default entities during policy evaluation
    • Add support for entity hierarchy traversal and parent relationship resolution
    • Create methods to check entity existence and retrieve entity collections
    • Requirements: 2.3, 3.2, 3.3, 4.2, 4.3

  • 5. Integrate default entity loading into Cedarling startup

    • Modify Cedarling initialization to detect and load default entities from policy store
    • Implement startup flow that loads entities after policy store parsing but before policy evaluation
    • Add configuration options to enable/disable default entity loading
    • Ensure Cedarling startup never fails due to default entity loading errors
    • Requirements: 2.1, 2.4, 2.5

  • 6. Implement schema validation for default entities

    • Create entity validation logic that checks entities against the Cedar schema
    • Implement validation for entity types, attributes, and parent relationships
    • Add support for optional vs required attribute validation
    • Create detailed validation error messages for troubleshooting
    • Requirements: 6.1, 6.2, 6.3, 6.4

  • 7. Add comprehensive error handling and logging

    • Implement LoadingResults model to track successful and failed entity loads
    • Create detailed error logging for parse failures, validation errors, and loading issues
    • Add performance metrics logging for entity loading times and memory usage
    • Implement error recovery that continues loading remaining entities after failures
    • Requirements: 2.5, 6.2

  • 8. Create unit tests for core components

    • Write unit tests for DefaultEntity model validation and attribute access
    • Create tests for PolicyStoreParser default entities parsing with various input scenarios
    • Implement tests for DefaultEntityLoader covering successful loads and error conditions
    • Add tests for EntityStore default entity storage and retrieval operations
    • Requirements: 1.1, 1.2, 1.3, 2.2, 2.3

  • 9. Develop integration tests for policy evaluation

    • Create test policies that reference default entities in authorization decisions
    • Implement tests for entity hierarchy traversal in policy conditions
    • Add tests for attribute-based authorization using default entity attributes
    • Create performance tests for policy evaluation with large numbers of default entities
    • Requirements: 3.1, 3.2, 3.3, 4.1, 4.2

  • 10. Add configuration and feature management

    • Implement DefaultEntityConfig with options for enabling/disabling the feature
    • Add configuration for maximum entity limits and validation strictness
    • Create feature flags to control default entity loading behavior
    • Implement configuration validation and default value handling
    • Requirements: 2.4, 2.5

  • 11. Implement backward compatibility safeguards

    • Ensure policy stores without default_entities section continue to work unchanged
    • Add version compatibility checks for Cedar schema and policy store format
    • Create migration utilities for existing policy stores
    • Implement graceful handling of unsupported default entity features
    • Requirements: 5.1, 5.2, 5.3, 5.4

  • 12. Create comprehensive test suite and documentation

    • Develop end-to-end tests covering complete default entity lifecycle
    • Create performance benchmarks for entity loading and policy evaluation
    • Write integration tests for various entity hierarchy and attribute scenarios
    • Add stress tests for large entity sets and concurrent access patterns
    • Requirements: 2.1, 2.2, 2.3, 3.1, 3.2, 4.1

Clone this wiki locally