Progressive Configuration Guide

Citadel is designed to grow with your needs. You can start with basic identity management and gradually layer on fine-grained permissions, attribute-based policies, and complex business workflows.

This guide walks you through the four levels of Citadel configuration.

---

🟢 Level 1: Identity & Admin Basics

At this level, you use Citadel as a centralized identity provider and administrative portal.

Key Components

• IAM Service: Manages users, roles, and groups.
• Admin Portal UI: The web interface for administrators to manage the platform.
• Shell App: The entry point for users, providing login and navigation.

Capabilities

• Self-Service Signup: Users can register via a simple flow (/signup?tenant_id=...).
• Role-Based Access (Basic): Assign users to standard roles (e.g., Admin, Member) defined in Keycloak.
• Tenant Management: Create and manage multiple organizations (tenants).

Progressive Step

Start by setting up a tenant and inviting your first few administrators. Use the Admin Portal to manually manage user memberships.

---

🟡 Level 2: Dynamic Policies (ABAC)

For logic that depends on attributes (e.g., "Allow access only during business hours" or "Only if the user's country matches the resource's country"), use Attribute-Based Access Control (ABAC).

Key Components

• Policy Service: A unified Decision Point (PDP) using the Cedar language.

Capabilities

• Cedar Policies: Write expressive policies using AWS's Cedar language.
• Unified Decision Point: The Policy Service handles policy evaluation using Cedar.
• Policy Simulation: Test "what-if" scenarios before deploying policies.

Example Policy

permit (
    principal,
    action == Action::"view",
    resource
)
when {
    resource.owner == principal ||
    principal.role == "admin"
};

---

🟠 Level 3: Fine-Grained Permissions (ReBAC)

When standard ABAC/RBAC rules are not enough and you have complex hierarchies, introduce Relationship-Based Access Control (ReBAC). The complexity of ReBAC is not for all apps, making it an advanced step.

Key Components

• Permissions Service: Powered by SpiceDB, it handles millions of relationship triples.

Capabilities

• Relationship Triples: Define access as relationships, e.g., document:123#viewer@user:alice.
• Graph Traversal: Check permissions through hierarchies (e.g., "Alice is a member of Team A, and Team A owns Folder B, so Alice can see Document C in Folder B").
• Centralized Schema: Manage your authorization schema in one place.

Progressive Step

Integrate the permissions-service into your application. Note: The Policy Service remains the single entry point. If the Permissions Service is enabled, the Policy Service will perform ReBAC checks first, get the decision from the Permissions Service, and inform the caller.

---

🔴 Level 4: Orchestrated Workflows (Sagas)

For complex, multi-step business processes that require reliability and consistency, use the Workflow Service.

Key Components

• Workflow Service: Based on Temporal, it implements the Orchestration-based Saga pattern.

Capabilities

• Long-Running Transactions: Handle processes that take minutes, hours, or days (e.g., onboarding approvals).
• Automated Compensation: If a step fails (e.g., billing setup fails), the service automatically runs "compensation" tasks (e.g., delete the created tenant) to keep the system consistent.
• Customizable Flows: Define flows like high_touch_signup which includes identity verification, KYC, and payment steps.

Progressive Step

Use the Workflow Service to automate "High-Touch" onboarding where an administrator must approve new organizations before they are provisioned.

---

Summary of the Journey

Feature	Level 1	Level 2	Level 3	Level 4
Logic	Basic Roles	Attributes/Conditions	Relationships	Stateful Processes
Service	IAM	Policy	Permissions	Workflow
UX	Simple Login	Policy-Driven UI	Resource Access	Guided Multi-Step Flows