6a59d34bb1
Update configuration files, templates, and internal documentation for the provisioning repository system. Configuration Updates: - KMS configuration modernization - Plugin system settings - Service port mappings - Test cluster topologies - Installation configuration examples - VM configuration defaults - Cedar authorization policies Documentation Updates: - Library module documentation - Extension API guides - AI system documentation - Service management guides - Test environment setup - Plugin usage guides - Validator configuration documentation All changes are backward compatible.
772 lines
37 KiB
HTML
772 lines
37 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Orchestrator Auth Integration - Provisioning Platform Documentation</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "../";
|
|
const default_light_theme = "ayu";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="mdbook-help-container">
|
|
<div id="mdbook-help-popup">
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|
<div>
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('ayu')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Provisioning Platform Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/provisioning/provisioning-platform" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/architecture/orchestrator-auth-integration.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="orchestrator-authentication--authorization-integration"><a class="header" href="#orchestrator-authentication--authorization-integration">Orchestrator Authentication & Authorization Integration</a></h1>
|
|
<p><strong>Version</strong>: 1.0.0
|
|
<strong>Date</strong>: 2025-10-08
|
|
<strong>Status</strong>: Implemented</p>
|
|
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
|
<p>Complete authentication and authorization flow integration for the Provisioning Orchestrator, connecting all security components (JWT validation, MFA verification, Cedar authorization, rate limiting, and audit logging) into a cohesive security middleware chain.</p>
|
|
<h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
|
|
<h3 id="security-middleware-chain"><a class="header" href="#security-middleware-chain">Security Middleware Chain</a></h3>
|
|
<p>The middleware chain is applied in this specific order to ensure proper security:</p>
|
|
<pre><code>┌─────────────────────────────────────────────────────────────────┐
|
|
│ Incoming HTTP Request │
|
|
└────────────────────────┬────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ 1. Rate Limiting Middleware │
|
|
│ - Per-IP request limits │
|
|
│ - Sliding window │
|
|
│ - Exempt IPs │
|
|
└────────────┬───────────────────┘
|
|
│ (429 if exceeded)
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ 2. Authentication Middleware │
|
|
│ - Extract Bearer token │
|
|
│ - Validate JWT signature │
|
|
│ - Check expiry, issuer, aud │
|
|
│ - Check revocation │
|
|
└────────────┬───────────────────┘
|
|
│ (401 if invalid)
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ 3. MFA Verification │
|
|
│ - Check MFA status in token │
|
|
│ - Enforce for sensitive ops │
|
|
│ - Production deployments │
|
|
│ - All DELETE operations │
|
|
└────────────┬───────────────────┘
|
|
│ (403 if required but missing)
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ 4. Authorization Middleware │
|
|
│ - Build Cedar request │
|
|
│ - Evaluate policies │
|
|
│ - Check permissions │
|
|
│ - Log decision │
|
|
└────────────┬───────────────────┘
|
|
│ (403 if denied)
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ 5. Audit Logging Middleware │
|
|
│ - Log complete request │
|
|
│ - User, action, resource │
|
|
│ - Authorization decision │
|
|
│ - Response status │
|
|
└────────────┬───────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────┐
|
|
│ Protected Handler │
|
|
│ - Access security context │
|
|
│ - Execute business logic │
|
|
└────────────────────────────────┘
|
|
</code></pre>
|
|
<h2 id="implementation-details"><a class="header" href="#implementation-details">Implementation Details</a></h2>
|
|
<h3 id="1-security-context-builder-middlewaresecurity_contextrs"><a class="header" href="#1-security-context-builder-middlewaresecurity_contextrs">1. Security Context Builder (<code>middleware/security_context.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: Build complete security context from authenticated requests.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li>Extracts JWT token claims</li>
|
|
<li>Determines MFA verification status</li>
|
|
<li>Extracts IP address (X-Forwarded-For, X-Real-IP)</li>
|
|
<li>Extracts user agent and session info</li>
|
|
<li>Provides permission checking methods</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 275</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-rust">pub struct SecurityContext {
|
|
pub user_id: String,
|
|
pub token: ValidatedToken,
|
|
pub mfa_verified: bool,
|
|
pub ip_address: IpAddr,
|
|
pub user_agent: Option<String>,
|
|
pub permissions: Vec<String>,
|
|
pub workspace: String,
|
|
pub request_id: String,
|
|
pub session_id: Option<String>,
|
|
}
|
|
|
|
impl SecurityContext {
|
|
pub fn has_permission(&self, permission: &str) -> bool { ... }
|
|
pub fn has_any_permission(&self, permissions: &[&str]) -> bool { ... }
|
|
pub fn has_all_permissions(&self, permissions: &[&str]) -> bool { ... }
|
|
}</code></pre>
|
|
<h3 id="2-enhanced-authentication-middleware-middlewareauthrs"><a class="header" href="#2-enhanced-authentication-middleware-middlewareauthrs">2. Enhanced Authentication Middleware (<code>middleware/auth.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: JWT token validation with revocation checking.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li>Bearer token extraction</li>
|
|
<li>JWT signature validation (RS256)</li>
|
|
<li>Expiry, issuer, audience checks</li>
|
|
<li>Token revocation status</li>
|
|
<li>Security context injection</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 245</p>
|
|
<p><strong>Flow</strong>:</p>
|
|
<ol>
|
|
<li>Extract <code>Authorization: Bearer <token></code> header</li>
|
|
<li>Validate JWT with TokenValidator</li>
|
|
<li>Build SecurityContext</li>
|
|
<li>Inject into request extensions</li>
|
|
<li>Continue to next middleware or return 401</li>
|
|
</ol>
|
|
<p><strong>Error Responses</strong>:</p>
|
|
<ul>
|
|
<li><code>401 Unauthorized</code>: Missing/invalid token, expired, revoked</li>
|
|
<li><code>403 Forbidden</code>: Insufficient permissions</li>
|
|
</ul>
|
|
<h3 id="3-mfa-verification-middleware-middlewaremfars"><a class="header" href="#3-mfa-verification-middleware-middlewaremfars">3. MFA Verification Middleware (<code>middleware/mfa.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: Enforce MFA for sensitive operations.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li>Path-based MFA requirements</li>
|
|
<li>Method-based enforcement (all DELETEs)</li>
|
|
<li>Production environment protection</li>
|
|
<li>Clear error messages</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 290</p>
|
|
<p><strong>MFA Required For</strong>:</p>
|
|
<ul>
|
|
<li>Production deployments (<code>/production/</code>, <code>/prod/</code>)</li>
|
|
<li>All DELETE operations</li>
|
|
<li>Server operations (POST, PUT, DELETE)</li>
|
|
<li>Cluster operations (POST, PUT, DELETE)</li>
|
|
<li>Batch submissions</li>
|
|
<li>Rollback operations</li>
|
|
<li>Configuration changes (POST, PUT, DELETE)</li>
|
|
<li>Secret management</li>
|
|
<li>User/role management</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-rust">fn requires_mfa(method: &str, path: &str) -> bool {
|
|
if path.contains("/production/") { return true; }
|
|
if method == "DELETE" { return true; }
|
|
if path.contains("/deploy") { return true; }
|
|
// ...
|
|
}</code></pre>
|
|
<h3 id="4-enhanced-authorization-middleware-middlewareauthzrs"><a class="header" href="#4-enhanced-authorization-middleware-middlewareauthzrs">4. Enhanced Authorization Middleware (<code>middleware/authz.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: Cedar policy evaluation with audit logging.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li>Builds Cedar authorization request from HTTP request</li>
|
|
<li>Maps HTTP methods to Cedar actions (GET→Read, POST→Create, etc.)</li>
|
|
<li>Extracts resource types from paths</li>
|
|
<li>Evaluates Cedar policies with context (MFA, IP, time, workspace)</li>
|
|
<li>Logs all authorization decisions to audit log</li>
|
|
<li>Non-blocking audit logging (tokio::spawn)</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 380</p>
|
|
<p><strong>Resource Mapping</strong>:</p>
|
|
<pre><code class="language-rust">/api/v1/servers/srv-123 → Resource::Server("srv-123")
|
|
/api/v1/taskserv/kubernetes → Resource::TaskService("kubernetes")
|
|
/api/v1/cluster/prod → Resource::Cluster("prod")
|
|
/api/v1/config/settings → Resource::Config("settings")</code></pre>
|
|
<p><strong>Action Mapping</strong>:</p>
|
|
<pre><code class="language-rust">GET → Action::Read
|
|
POST → Action::Create
|
|
PUT → Action::Update
|
|
DELETE → Action::Delete</code></pre>
|
|
<h3 id="5-rate-limiting-middleware-middlewarerate_limitrs"><a class="header" href="#5-rate-limiting-middleware-middlewarerate_limitrs">5. Rate Limiting Middleware (<code>middleware/rate_limit.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: Prevent API abuse with per-IP rate limiting.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li>Sliding window rate limiting</li>
|
|
<li>Per-IP request tracking</li>
|
|
<li>Configurable limits and windows</li>
|
|
<li>Exempt IP support</li>
|
|
<li>Automatic cleanup of old entries</li>
|
|
<li>Statistics tracking</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 420</p>
|
|
<p><strong>Configuration</strong>:</p>
|
|
<pre><code class="language-rust">pub struct RateLimitConfig {
|
|
pub max_requests: u32, // e.g., 100
|
|
pub window_duration: Duration, // e.g., 60 seconds
|
|
pub exempt_ips: Vec<IpAddr>, // e.g., internal services
|
|
pub enabled: bool,
|
|
}
|
|
|
|
// Default: 100 requests per minute</code></pre>
|
|
<p><strong>Statistics</strong>:</p>
|
|
<pre><code class="language-rust">pub struct RateLimitStats {
|
|
pub total_ips: usize, // Number of tracked IPs
|
|
pub total_requests: u32, // Total requests made
|
|
pub limited_ips: usize, // IPs that hit the limit
|
|
pub config: RateLimitConfig,
|
|
}</code></pre>
|
|
<h3 id="6-security-integration-module-security_integrationrs"><a class="header" href="#6-security-integration-module-security_integrationrs">6. Security Integration Module (<code>security_integration.rs</code>)</a></h3>
|
|
<p><strong>Purpose</strong>: Helper module to integrate all security components.</p>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul>
|
|
<li><code>SecurityComponents</code> struct grouping all middleware</li>
|
|
<li><code>SecurityConfig</code> for configuration</li>
|
|
<li><code>initialize()</code> method to set up all components</li>
|
|
<li><code>disabled()</code> method for development mode</li>
|
|
<li><code>apply_security_middleware()</code> helper for router setup</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 265</p>
|
|
<p><strong>Usage Example</strong>:</p>
|
|
<pre><code class="language-rust">use provisioning_orchestrator::security_integration::{
|
|
SecurityComponents, SecurityConfig
|
|
};
|
|
|
|
// Initialize security
|
|
let config = SecurityConfig {
|
|
public_key_path: PathBuf::from("keys/public.pem"),
|
|
jwt_issuer: "control-center".to_string(),
|
|
jwt_audience: "orchestrator".to_string(),
|
|
cedar_policies_path: PathBuf::from("policies"),
|
|
auth_enabled: true,
|
|
authz_enabled: true,
|
|
mfa_enabled: true,
|
|
rate_limit_config: RateLimitConfig::new(100, 60),
|
|
};
|
|
|
|
let security = SecurityComponents::initialize(config, audit_logger).await?;
|
|
|
|
// Apply to router
|
|
let app = Router::new()
|
|
.route("/api/v1/servers", post(create_server))
|
|
.route("/api/v1/servers/:id", delete(delete_server));
|
|
|
|
let secured_app = apply_security_middleware(app, &security);</code></pre>
|
|
<h2 id="integration-with-appstate"><a class="header" href="#integration-with-appstate">Integration with AppState</a></h2>
|
|
<h3 id="updated-appstate-structure"><a class="header" href="#updated-appstate-structure">Updated AppState Structure</a></h3>
|
|
<pre><code class="language-rust">pub struct AppState {
|
|
// Existing fields
|
|
pub task_storage: Arc<dyn TaskStorage>,
|
|
pub batch_coordinator: BatchCoordinator,
|
|
pub dependency_resolver: DependencyResolver,
|
|
pub state_manager: Arc<WorkflowStateManager>,
|
|
pub monitoring_system: Arc<MonitoringSystem>,
|
|
pub progress_tracker: Arc<ProgressTracker>,
|
|
pub rollback_system: Arc<RollbackSystem>,
|
|
pub test_orchestrator: Arc<TestOrchestrator>,
|
|
pub dns_manager: Arc<DnsManager>,
|
|
pub extension_manager: Arc<ExtensionManager>,
|
|
pub oci_manager: Arc<OciManager>,
|
|
pub service_orchestrator: Arc<ServiceOrchestrator>,
|
|
pub audit_logger: Arc<AuditLogger>,
|
|
pub args: Args,
|
|
|
|
// NEW: Security components
|
|
pub security: SecurityComponents,
|
|
}</code></pre>
|
|
<h3 id="initialization-in-mainrs"><a class="header" href="#initialization-in-mainrs">Initialization in main.rs</a></h3>
|
|
<pre><code class="language-rust">#[tokio::main]
|
|
async fn main() -> Result<()> {
|
|
let args = Args::parse();
|
|
|
|
// Initialize AppState (creates audit_logger)
|
|
let state = Arc::new(AppState::new(args).await?);
|
|
|
|
// Initialize security components
|
|
let security_config = SecurityConfig {
|
|
public_key_path: PathBuf::from("keys/public.pem"),
|
|
jwt_issuer: env::var("JWT_ISSUER").unwrap_or("control-center".to_string()),
|
|
jwt_audience: "orchestrator".to_string(),
|
|
cedar_policies_path: PathBuf::from("policies"),
|
|
auth_enabled: env::var("AUTH_ENABLED").unwrap_or("true".to_string()) == "true",
|
|
authz_enabled: env::var("AUTHZ_ENABLED").unwrap_or("true".to_string()) == "true",
|
|
mfa_enabled: env::var("MFA_ENABLED").unwrap_or("true".to_string()) == "true",
|
|
rate_limit_config: RateLimitConfig::new(
|
|
env::var("RATE_LIMIT_MAX").unwrap_or("100".to_string()).parse().unwrap(),
|
|
env::var("RATE_LIMIT_WINDOW").unwrap_or("60".to_string()).parse().unwrap(),
|
|
),
|
|
};
|
|
|
|
let security = SecurityComponents::initialize(
|
|
security_config,
|
|
state.audit_logger.clone()
|
|
).await?;
|
|
|
|
// Public routes (no auth)
|
|
let public_routes = Router::new()
|
|
.route("/health", get(health_check));
|
|
|
|
// Protected routes (full security chain)
|
|
let protected_routes = Router::new()
|
|
.route("/api/v1/servers", post(create_server))
|
|
.route("/api/v1/servers/:id", delete(delete_server))
|
|
.route("/api/v1/taskserv", post(create_taskserv))
|
|
.route("/api/v1/cluster", post(create_cluster))
|
|
// ... more routes
|
|
;
|
|
|
|
// Apply security middleware to protected routes
|
|
let secured_routes = apply_security_middleware(protected_routes, &security)
|
|
.with_state(state.clone());
|
|
|
|
// Combine routes
|
|
let app = Router::new()
|
|
.merge(public_routes)
|
|
.merge(secured_routes)
|
|
.layer(CorsLayer::permissive());
|
|
|
|
// Start server
|
|
let listener = tokio::net::TcpListener::bind("0.0.0.0:9090").await?;
|
|
axum::serve(listener, app).await?;
|
|
|
|
Ok(())
|
|
}</code></pre>
|
|
<h2 id="protected-endpoints"><a class="header" href="#protected-endpoints">Protected Endpoints</a></h2>
|
|
<h3 id="endpoint-categories"><a class="header" href="#endpoint-categories">Endpoint Categories</a></h3>
|
|
<div class="table-wrapper"><table><thead><tr><th>Category</th><th>Example Endpoints</th><th>Auth Required</th><th>MFA Required</th><th>Cedar Policy</th></tr></thead><tbody>
|
|
<tr><td><strong>Health</strong></td><td><code>/health</code></td><td>❌</td><td>❌</td><td>❌</td></tr>
|
|
<tr><td><strong>Read-Only</strong></td><td><code>GET /api/v1/servers</code></td><td>✅</td><td>❌</td><td>✅</td></tr>
|
|
<tr><td><strong>Server Mgmt</strong></td><td><code>POST /api/v1/servers</code></td><td>✅</td><td>❌</td><td>✅</td></tr>
|
|
<tr><td><strong>Server Delete</strong></td><td><code>DELETE /api/v1/servers/:id</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Taskserv Mgmt</strong></td><td><code>POST /api/v1/taskserv</code></td><td>✅</td><td>❌</td><td>✅</td></tr>
|
|
<tr><td><strong>Cluster Mgmt</strong></td><td><code>POST /api/v1/cluster</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Production</strong></td><td><code>POST /api/v1/production/*</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Batch Ops</strong></td><td><code>POST /api/v1/batch/submit</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Rollback</strong></td><td><code>POST /api/v1/rollback</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Config Write</strong></td><td><code>POST /api/v1/config</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
<tr><td><strong>Secrets</strong></td><td><code>GET /api/v1/secret/*</code></td><td>✅</td><td>✅</td><td>✅</td></tr>
|
|
</tbody></table>
|
|
</div>
|
|
<h2 id="complete-authentication-flow"><a class="header" href="#complete-authentication-flow">Complete Authentication Flow</a></h2>
|
|
<h3 id="step-by-step-flow"><a class="header" href="#step-by-step-flow">Step-by-Step Flow</a></h3>
|
|
<pre><code>1. CLIENT REQUEST
|
|
├─ Headers:
|
|
│ ├─ Authorization: Bearer <jwt_token>
|
|
│ ├─ X-Forwarded-For: 192.168.1.100
|
|
│ ├─ User-Agent: MyClient/1.0
|
|
│ └─ X-MFA-Verified: true
|
|
└─ Path: DELETE /api/v1/servers/prod-srv-01
|
|
|
|
2. RATE LIMITING MIDDLEWARE
|
|
├─ Extract IP: 192.168.1.100
|
|
├─ Check limit: 45/100 requests in window
|
|
├─ Decision: ALLOW (under limit)
|
|
└─ Continue →
|
|
|
|
3. AUTHENTICATION MIDDLEWARE
|
|
├─ Extract Bearer token
|
|
├─ Validate JWT:
|
|
│ ├─ Signature: ✅ Valid (RS256)
|
|
│ ├─ Expiry: ✅ Valid until 2025-10-09 10:00:00
|
|
│ ├─ Issuer: ✅ control-center
|
|
│ ├─ Audience: ✅ orchestrator
|
|
│ └─ Revoked: ✅ Not revoked
|
|
├─ Build SecurityContext:
|
|
│ ├─ user_id: "user-456"
|
|
│ ├─ workspace: "production"
|
|
│ ├─ permissions: ["read", "write", "delete"]
|
|
│ ├─ mfa_verified: true
|
|
│ └─ ip_address: 192.168.1.100
|
|
├─ Decision: ALLOW (valid token)
|
|
└─ Continue →
|
|
|
|
4. MFA VERIFICATION MIDDLEWARE
|
|
├─ Check endpoint: DELETE /api/v1/servers/prod-srv-01
|
|
├─ Requires MFA: ✅ YES (DELETE operation)
|
|
├─ MFA status: ✅ Verified
|
|
├─ Decision: ALLOW (MFA verified)
|
|
└─ Continue →
|
|
|
|
5. AUTHORIZATION MIDDLEWARE
|
|
├─ Build Cedar request:
|
|
│ ├─ Principal: User("user-456")
|
|
│ ├─ Action: Delete
|
|
│ ├─ Resource: Server("prod-srv-01")
|
|
│ └─ Context:
|
|
│ ├─ mfa_verified: true
|
|
│ ├─ ip_address: "192.168.1.100"
|
|
│ ├─ time: 2025-10-08T14:30:00Z
|
|
│ └─ workspace: "production"
|
|
├─ Evaluate Cedar policies:
|
|
│ ├─ Policy 1: Allow if user.role == "admin" ✅
|
|
│ ├─ Policy 2: Allow if mfa_verified == true ✅
|
|
│ └─ Policy 3: Deny if not business_hours ❌
|
|
├─ Decision: ALLOW (2 allow, 1 deny = allow)
|
|
├─ Log to audit: Authorization GRANTED
|
|
└─ Continue →
|
|
|
|
6. AUDIT LOGGING MIDDLEWARE
|
|
├─ Record:
|
|
│ ├─ User: user-456 (IP: 192.168.1.100)
|
|
│ ├─ Action: ServerDelete
|
|
│ ├─ Resource: prod-srv-01
|
|
│ ├─ Authorization: GRANTED
|
|
│ ├─ MFA: Verified
|
|
│ └─ Timestamp: 2025-10-08T14:30:00Z
|
|
└─ Continue →
|
|
|
|
7. PROTECTED HANDLER
|
|
├─ Execute business logic
|
|
├─ Delete server prod-srv-01
|
|
└─ Return: 200 OK
|
|
|
|
8. AUDIT LOGGING (Response)
|
|
├─ Update event:
|
|
│ ├─ Status: 200 OK
|
|
│ ├─ Duration: 1.234s
|
|
│ └─ Result: SUCCESS
|
|
└─ Write to audit log
|
|
|
|
9. CLIENT RESPONSE
|
|
└─ 200 OK: Server deleted successfully
|
|
</code></pre>
|
|
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
|
<h3 id="environment-variables"><a class="header" href="#environment-variables">Environment Variables</a></h3>
|
|
<pre><code class="language-bash"># JWT Configuration
|
|
JWT_ISSUER=control-center
|
|
JWT_AUDIENCE=orchestrator
|
|
PUBLIC_KEY_PATH=/path/to/keys/public.pem
|
|
|
|
# Cedar Policies
|
|
CEDAR_POLICIES_PATH=/path/to/policies
|
|
|
|
# Security Toggles
|
|
AUTH_ENABLED=true
|
|
AUTHZ_ENABLED=true
|
|
MFA_ENABLED=true
|
|
|
|
# Rate Limiting
|
|
RATE_LIMIT_MAX=100
|
|
RATE_LIMIT_WINDOW=60
|
|
RATE_LIMIT_EXEMPT_IPS=10.0.0.1,10.0.0.2
|
|
|
|
# Audit Logging
|
|
AUDIT_ENABLED=true
|
|
AUDIT_RETENTION_DAYS=365
|
|
</code></pre>
|
|
<h3 id="development-mode"><a class="header" href="#development-mode">Development Mode</a></h3>
|
|
<p>For development/testing, all security can be disabled:</p>
|
|
<pre><code class="language-rust">// In main.rs
|
|
let security = if env::var("DEVELOPMENT_MODE").unwrap_or("false".to_string()) == "true" {
|
|
SecurityComponents::disabled(audit_logger.clone())
|
|
} else {
|
|
SecurityComponents::initialize(security_config, audit_logger.clone()).await?
|
|
};</code></pre>
|
|
<h2 id="testing"><a class="header" href="#testing">Testing</a></h2>
|
|
<h3 id="integration-tests"><a class="header" href="#integration-tests">Integration Tests</a></h3>
|
|
<p>Location: <code>provisioning/platform/orchestrator/tests/security_integration_tests.rs</code></p>
|
|
<p><strong>Test Coverage</strong>:</p>
|
|
<ul>
|
|
<li>✅ Rate limiting enforcement</li>
|
|
<li>✅ Rate limit statistics</li>
|
|
<li>✅ Exempt IP handling</li>
|
|
<li>✅ Authentication missing token</li>
|
|
<li>✅ MFA verification for sensitive operations</li>
|
|
<li>✅ Cedar policy evaluation</li>
|
|
<li>✅ Complete security flow</li>
|
|
<li>✅ Security components initialization</li>
|
|
<li>✅ Configuration defaults</li>
|
|
</ul>
|
|
<p><strong>Lines of Code</strong>: 340</p>
|
|
<p><strong>Run Tests</strong>:</p>
|
|
<pre><code class="language-bash">cd provisioning/platform/orchestrator
|
|
cargo test security_integration_tests
|
|
</code></pre>
|
|
<h2 id="file-summary"><a class="header" href="#file-summary">File Summary</a></h2>
|
|
<div class="table-wrapper"><table><thead><tr><th>File</th><th>Purpose</th><th>Lines</th><th>Tests</th></tr></thead><tbody>
|
|
<tr><td><code>middleware/security_context.rs</code></td><td>Security context builder</td><td>275</td><td>8</td></tr>
|
|
<tr><td><code>middleware/auth.rs</code></td><td>JWT authentication</td><td>245</td><td>5</td></tr>
|
|
<tr><td><code>middleware/mfa.rs</code></td><td>MFA verification</td><td>290</td><td>15</td></tr>
|
|
<tr><td><code>middleware/authz.rs</code></td><td>Cedar authorization</td><td>380</td><td>4</td></tr>
|
|
<tr><td><code>middleware/rate_limit.rs</code></td><td>Rate limiting</td><td>420</td><td>8</td></tr>
|
|
<tr><td><code>middleware/mod.rs</code></td><td>Module exports</td><td>25</td><td>0</td></tr>
|
|
<tr><td><code>security_integration.rs</code></td><td>Integration helpers</td><td>265</td><td>2</td></tr>
|
|
<tr><td><code>tests/security_integration_tests.rs</code></td><td>Integration tests</td><td>340</td><td>11</td></tr>
|
|
<tr><td><strong>Total</strong></td><td></td><td><strong>2,240</strong></td><td><strong>53</strong></td></tr>
|
|
</tbody></table>
|
|
</div>
|
|
<h2 id="benefits"><a class="header" href="#benefits">Benefits</a></h2>
|
|
<h3 id="security"><a class="header" href="#security">Security</a></h3>
|
|
<ul>
|
|
<li>✅ Complete authentication flow with JWT validation</li>
|
|
<li>✅ MFA enforcement for sensitive operations</li>
|
|
<li>✅ Fine-grained authorization with Cedar policies</li>
|
|
<li>✅ Rate limiting prevents API abuse</li>
|
|
<li>✅ Complete audit trail for compliance</li>
|
|
</ul>
|
|
<h3 id="architecture-1"><a class="header" href="#architecture-1">Architecture</a></h3>
|
|
<ul>
|
|
<li>✅ Modular middleware design</li>
|
|
<li>✅ Clear separation of concerns</li>
|
|
<li>✅ Reusable security components</li>
|
|
<li>✅ Easy to test and maintain</li>
|
|
<li>✅ Configuration-driven behavior</li>
|
|
</ul>
|
|
<h3 id="operations"><a class="header" href="#operations">Operations</a></h3>
|
|
<ul>
|
|
<li>✅ Can enable/disable features independently</li>
|
|
<li>✅ Development mode for testing</li>
|
|
<li>✅ Comprehensive error messages</li>
|
|
<li>✅ Real-time statistics and monitoring</li>
|
|
<li>✅ Non-blocking audit logging</li>
|
|
</ul>
|
|
<h2 id="future-enhancements"><a class="header" href="#future-enhancements">Future Enhancements</a></h2>
|
|
<ol>
|
|
<li><strong>Token Refresh</strong>: Automatic token refresh before expiry</li>
|
|
<li><strong>IP Whitelisting</strong>: Additional IP-based access control</li>
|
|
<li><strong>Geolocation</strong>: Block requests from specific countries</li>
|
|
<li><strong>Advanced Rate Limiting</strong>: Per-user, per-endpoint limits</li>
|
|
<li><strong>Session Management</strong>: Track active sessions, force logout</li>
|
|
<li><strong>2FA Integration</strong>: Direct integration with TOTP/SMS providers</li>
|
|
<li><strong>Policy Hot Reload</strong>: Update Cedar policies without restart</li>
|
|
<li><strong>Metrics Dashboard</strong>: Real-time security metrics visualization</li>
|
|
</ol>
|
|
<h2 id="related-documentation"><a class="header" href="#related-documentation">Related Documentation</a></h2>
|
|
<ul>
|
|
<li><a href="../../security/cedar-policies.html">Cedar Policy Language</a></li>
|
|
<li><a href="../../security/jwt-tokens.html">JWT Token Management</a></li>
|
|
<li><a href="../../security/mfa-setup.html">MFA Setup Guide</a></li>
|
|
<li><a href="../../security/audit-logs.html">Audit Log Format</a></li>
|
|
<li><a href="../../security/rate-limiting.html">Rate Limiting Best Practices</a></li>
|
|
</ul>
|
|
<h2 id="version-history"><a class="header" href="#version-history">Version History</a></h2>
|
|
<div class="table-wrapper"><table><thead><tr><th>Version</th><th>Date</th><th>Changes</th></tr></thead><tbody>
|
|
<tr><td>1.0.0</td><td>2025-10-08</td><td>Initial implementation</td></tr>
|
|
</tbody></table>
|
|
</div>
|
|
<hr />
|
|
<p><strong>Maintained By</strong>: Security Team
|
|
<strong>Review Cycle</strong>: Quarterly
|
|
<strong>Last Reviewed</strong>: 2025-10-08</p>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../architecture/MFA_IMPLEMENTATION_SUMMARY.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../platform/index.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../architecture/MFA_IMPLEMENTATION_SUMMARY.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../platform/index.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
<!-- Livereload script (if served using the cli tool) -->
|
|
<script>
|
|
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
|
const socket = new WebSocket(wsAddress);
|
|
socket.onmessage = function (event) {
|
|
if (event.data === "reload") {
|
|
socket.close();
|
|
location.reload();
|
|
}
|
|
};
|
|
|
|
window.onbeforeunload = function() {
|
|
socket.close();
|
|
}
|
|
</script>
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js"></script>
|
|
<script src="../mark.min.js"></script>
|
|
<script src="../searcher.js"></script>
|
|
|
|
<script src="../clipboard.min.js"></script>
|
|
<script src="../highlight.js"></script>
|
|
<script src="../book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|