Skip to content

Cedarling Technical Specification Document

Jump to bottom
Moaz bin Mokhtar edited this page Sep 3, 2024 · 5 revisions

Technical Specification Document for Cedarling

Product Scope

The Cedarling is a WASM component library which is a performant local authorization service that runs the Rust Cedar Engine. It provides fine-grained and responsive policy management capabilities, allowing developers to create complex, contextual policies without cluttering application code with numerous conditional statements.

Key features of the Cedarling include:

  • Local caching of policies and schemas
  • Deterministic policy evaluation
  • Support for RBAC and custom policies
  • JWT token validation
  • Audit logging of authorization decisions

Engines

Cedarling consists of several engines as summarized below:

  • Init Engine
    • From Log Engine, enable logging
    • Read bootstrap properties
    • From Cedar Engine:
      • Load Schema
      • Load policy store
  • Authz Engine
    • From Log Engine, enable logging
    • From JWT Engine:
      • Extract data JWTs
      • Validate JWTs
      • Map JWTs into entities
    • From Cedar Engine:
      • Evaluate policies
        • Evaluate if User allowed
        • Evaluate if Client allowed
    • From Lock Engine:
      • Insert evaluation into logs /audit
  • JWT Engine
    • Extract data from JSON (JWTs)
    • Validate JWT signature and status
    • Construct Entities and context
  • Log Engine
    • Log all authz and init events
  • Cedar Engine
    • Communicate with Cedar instance
    • Load Schema
    • From Lock Engine, Load policy store /config
    • Evaluate policies
  • Lock Engine
    • Dynamic Client Registration
    • Get policy store from /config
    • POST logs to /audit endpoint
    • POST /sse endpoint

Request structure and Main Models

Sample request sent by JS who calling the Cedarling WASM component:

input = {
  access_token: "eyJhbGc....",
  id_token: "eyJjbGc...",
  userinfo_token: "eyJjbGc...",
  tx_token: "eyJjbGc...",
  action: "View",
  resource: {
    Ticket: {
      id: "ticket-10101",
      owner: "bob@acme.com",
      org_id: "Acme",
    },
  },
  context: {
    ip_address: "54.9.21.201",
    network_type: "VPN",
    user_agent: "Chrome 125.0.6422.77 (Official Build) (arm64)",
    time: "1719266610.98636",
  },
};

decision_result = authz(input);

diagram for auth jwt tokens

Core schema:

namespace Jans {
    // ******  TYPES  ******
    type Url = {
        protocol: String,
        host: String,
        path: String,
    };
    type email_address = {
        id: String,
        domain: String,
    };
    type Context = {
            network: ipaddr,
            network_type: String,
            user_agent: String,
            operating_system: String,
            device_health: Set<String>,
            current_time: Long,
            geolocation: Set<String>,
            fraud_indicators: Set<String>,
    };

    // ******  Entities  ******
    entity TrustedIssuer = {
        issuer_entity_id: Url,
    };
    entity Client  = {
        client_id: String,
        iss: TrustedIssuer,
    };
    entity Application = {
        name: String,
        client: Client,
    };
    entity Role;
    entity User in [Role] {
        sub: String,
        username: String,
        email: email_address,
        phone_number: String,
        role: Set<String>,
    };

    entity Access_token  = {
        aud: String,
        exp: Long,
        iat: Long,
        iss: TrustedIssuer,
        jti: String,
        nbf: Long,
        scope: String,
    };
    entity id_token  = {
        acr: Set<String>,
        amr: String,
        aud: String,
        azp: String,
        birthdate: String,
        email: email_address,
        exp: Long,
        iat: Long,
        iss: TrustedIssuer,
        jti: String,
        name: String,
        phone_number: String,
        role: Set<String>,
        sub: String,
    };
    entity Userinfo_token  = {
        aud: String,
        birthdate: String,
        email: email_address,
        exp: Long,
        iat: Long,
        iss: TrustedIssuer,
        jti: String,
        name: String,
        phone_number: String,
        role: Set<String>,
        sub: String,
    };
}

Main Models

  • InputRequest: input sent to Cedarling WASM
 pub struct InputRequest {
   pub access_token: AccessToken,
   pub id_token: IdToken,
   pub userinfo_token: UserInfoToken,
   pub tx_token: TxToken,
   pub action: Entity,
   pub resource: Entity,
   pub context: Entity,
 }
  • IdToken: containing user information
pub struct IdToken {
    pub acr: Vec<String>,
    pub amr: String,
    pub aud: String,
    pub azp: String,
    pub birthdate: String,
    pub email: String,
    pub exp: i64,
    pub iat: i64,
    pub iss: TrustedIssuer,
    pub jti: String,
    pub name: String,
    pub phone_number: Option<String>,
    pub role: Vec<String>,
    pub sub: String,
}
  • AccessToken: Represents an access token
pub struct AccessToken {
    pub aud: String,
    pub exp: i64,
    pub iat: i64,
    pub iss: TrustedIssuer,
    pub jti: String,
    pub scope: String,
}
  • UserInfoToken
pub struct UserInfoToken {
    pub aud: String,
    pub birthdate: String,
    pub email: String,
    pub exp: i64,
    pub iat: i64,
    pub iss: TrustedIssuer,
    pub jti: String,
    pub name: String,
    pub phone_number: String,
    pub role: Vec<String>,
    pub sub: String,
}
  • TxToken (Transaction Token): //TODO
  • Entity: A principal, an action, or a resource that is part of your application are all represented in Cedar as entities. Entities are referenced by their type and identifier, together called the entity’s unique identifier (UID).
pub struct Entity {
    type: String, //TODO: type to be changed
    Identifier: String, //TODO: type to be changed
}
  • Context: used to provide details specific to a request, such as the date and time the request was sent, the IP address the request originated from, or whether the user was authenticated using a multi-factor authentication device.
pub struct Context {
    pub ip_address: IpAddr,
    pub network_type: String,
    pub user_agent: String,
    pub operating_system: String,
    pub device_health: Vec<String>,
    pub current_time: i64,
    pub geolocation: Vec<String>,
    pub fraud_indicators: Vec<String>,
}
  • User
pub struct User {
    pub sub: String,
    pub username: String,
    pub email: String,
    pub phone_number: String,
    pub role: String,
}
  • Client
pub struct Client {
    pub client_id: String,
    pub iss: TrustedIssuer,
}

References

Clone this wiki locally