44648e3206
- Remove KCL ecosystem (~220 files deleted) - Migrate all infrastructure to Nickel schema system - Consolidate documentation: legacy docs → provisioning/docs/src/ - Add CI/CD workflows (.github/) and Rust build config (.cargo/) - Update core system for Nickel schema parsing - Update README.md and CHANGES.md for v5.0.0 release - Fix pre-commit hooks: end-of-file, trailing-whitespace - Breaking changes: KCL workspaces require migration - Migration bridge available in docs/src/development/
840 lines
31 KiB
HTML
840 lines
31 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 class="language-plaintext">┌─────────────────────────────────────────────────────────────────┐
|
|
│ 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 │
|
|
└────────────────────────────────┘
|
|
```plaintext
|
|
|
|
## Implementation Details
|
|
|
|
### 1. Security Context Builder (`middleware/security_context.rs`)
|
|
|
|
**Purpose**: Build complete security context from authenticated requests.
|
|
|
|
**Key Features**:
|
|
|
|
- Extracts JWT token claims
|
|
- Determines MFA verification status
|
|
- Extracts IP address (X-Forwarded-For, X-Real-IP)
|
|
- Extracts user agent and session info
|
|
- Provides permission checking methods
|
|
|
|
**Lines of Code**: 275
|
|
|
|
**Example**:
|
|
|
|
```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 { ... }
|
|
}
|
|
```plaintext
|
|
|
|
### 2. Enhanced Authentication Middleware (`middleware/auth.rs`)
|
|
|
|
**Purpose**: JWT token validation with revocation checking.
|
|
|
|
**Key Features**:
|
|
|
|
- Bearer token extraction
|
|
- JWT signature validation (RS256)
|
|
- Expiry, issuer, audience checks
|
|
- Token revocation status
|
|
- Security context injection
|
|
|
|
**Lines of Code**: 245
|
|
|
|
**Flow**:
|
|
|
|
1. Extract `Authorization: Bearer <token>` header
|
|
2. Validate JWT with TokenValidator
|
|
3. Build SecurityContext
|
|
4. Inject into request extensions
|
|
5. Continue to next middleware or return 401
|
|
|
|
**Error Responses**:
|
|
|
|
- `401 Unauthorized`: Missing/invalid token, expired, revoked
|
|
- `403 Forbidden`: Insufficient permissions
|
|
|
|
### 3. MFA Verification Middleware (`middleware/mfa.rs`)
|
|
|
|
**Purpose**: Enforce MFA for sensitive operations.
|
|
|
|
**Key Features**:
|
|
|
|
- Path-based MFA requirements
|
|
- Method-based enforcement (all DELETEs)
|
|
- Production environment protection
|
|
- Clear error messages
|
|
|
|
**Lines of Code**: 290
|
|
|
|
**MFA Required For**:
|
|
|
|
- Production deployments (`/production/`, `/prod/`)
|
|
- All DELETE operations
|
|
- Server operations (POST, PUT, DELETE)
|
|
- Cluster operations (POST, PUT, DELETE)
|
|
- Batch submissions
|
|
- Rollback operations
|
|
- Configuration changes (POST, PUT, DELETE)
|
|
- Secret management
|
|
- User/role management
|
|
|
|
**Example**:
|
|
|
|
```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; }
|
|
// ...
|
|
}
|
|
```plaintext
|
|
|
|
### 4. Enhanced Authorization Middleware (`middleware/authz.rs`)
|
|
|
|
**Purpose**: Cedar policy evaluation with audit logging.
|
|
|
|
**Key Features**:
|
|
|
|
- Builds Cedar authorization request from HTTP request
|
|
- Maps HTTP methods to Cedar actions (GET→Read, POST→Create, etc.)
|
|
- Extracts resource types from paths
|
|
- Evaluates Cedar policies with context (MFA, IP, time, workspace)
|
|
- Logs all authorization decisions to audit log
|
|
- Non-blocking audit logging (tokio::spawn)
|
|
|
|
**Lines of Code**: 380
|
|
|
|
**Resource Mapping**:
|
|
|
|
```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")
|
|
```plaintext
|
|
|
|
**Action Mapping**:
|
|
|
|
```rust
|
|
GET → Action::Read
|
|
POST → Action::Create
|
|
PUT → Action::Update
|
|
DELETE → Action::Delete
|
|
```plaintext
|
|
|
|
### 5. Rate Limiting Middleware (`middleware/rate_limit.rs`)
|
|
|
|
**Purpose**: Prevent API abuse with per-IP rate limiting.
|
|
|
|
**Key Features**:
|
|
|
|
- Sliding window rate limiting
|
|
- Per-IP request tracking
|
|
- Configurable limits and windows
|
|
- Exempt IP support
|
|
- Automatic cleanup of old entries
|
|
- Statistics tracking
|
|
|
|
**Lines of Code**: 420
|
|
|
|
**Configuration**:
|
|
|
|
```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
|
|
```plaintext
|
|
|
|
**Statistics**:
|
|
|
|
```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,
|
|
}
|
|
```plaintext
|
|
|
|
### 6. Security Integration Module (`security_integration.rs`)
|
|
|
|
**Purpose**: Helper module to integrate all security components.
|
|
|
|
**Key Features**:
|
|
|
|
- `SecurityComponents` struct grouping all middleware
|
|
- `SecurityConfig` for configuration
|
|
- `initialize()` method to set up all components
|
|
- `disabled()` method for development mode
|
|
- `apply_security_middleware()` helper for router setup
|
|
|
|
**Lines of Code**: 265
|
|
|
|
**Usage Example**:
|
|
|
|
```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);
|
|
```plaintext
|
|
|
|
## Integration with AppState
|
|
|
|
### Updated AppState Structure
|
|
|
|
```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,
|
|
}
|
|
```plaintext
|
|
|
|
### Initialization in main.rs
|
|
|
|
```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(())
|
|
}
|
|
```plaintext
|
|
|
|
## Protected Endpoints
|
|
|
|
### Endpoint Categories
|
|
|
|
| Category | Example Endpoints | Auth Required | MFA Required | Cedar Policy |
|
|
|----------|-------------------|---------------|--------------|--------------|
|
|
| **Health** | `/health` | ❌ | ❌ | ❌ |
|
|
| **Read-Only** | `GET /api/v1/servers` | ✅ | ❌ | ✅ |
|
|
| **Server Mgmt** | `POST /api/v1/servers` | ✅ | ❌ | ✅ |
|
|
| **Server Delete** | `DELETE /api/v1/servers/:id` | ✅ | ✅ | ✅ |
|
|
| **Taskserv Mgmt** | `POST /api/v1/taskserv` | ✅ | ❌ | ✅ |
|
|
| **Cluster Mgmt** | `POST /api/v1/cluster` | ✅ | ✅ | ✅ |
|
|
| **Production** | `POST /api/v1/production/*` | ✅ | ✅ | ✅ |
|
|
| **Batch Ops** | `POST /api/v1/batch/submit` | ✅ | ✅ | ✅ |
|
|
| **Rollback** | `POST /api/v1/rollback` | ✅ | ✅ | ✅ |
|
|
| **Config Write** | `POST /api/v1/config` | ✅ | ✅ | ✅ |
|
|
| **Secrets** | `GET /api/v1/secret/*` | ✅ | ✅ | ✅ |
|
|
|
|
## Complete Authentication Flow
|
|
|
|
### Step-by-Step Flow
|
|
|
|
```plaintext
|
|
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
|
|
```plaintext
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```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
|
|
```plaintext
|
|
|
|
### Development Mode
|
|
|
|
For development/testing, all security can be disabled:
|
|
|
|
```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?
|
|
};
|
|
```plaintext
|
|
|
|
## Testing
|
|
|
|
### Integration Tests
|
|
|
|
Location: `provisioning/platform/orchestrator/tests/security_integration_tests.rs`
|
|
|
|
**Test Coverage**:
|
|
|
|
- ✅ Rate limiting enforcement
|
|
- ✅ Rate limit statistics
|
|
- ✅ Exempt IP handling
|
|
- ✅ Authentication missing token
|
|
- ✅ MFA verification for sensitive operations
|
|
- ✅ Cedar policy evaluation
|
|
- ✅ Complete security flow
|
|
- ✅ Security components initialization
|
|
- ✅ Configuration defaults
|
|
|
|
**Lines of Code**: 340
|
|
|
|
**Run Tests**:
|
|
|
|
```bash
|
|
cd provisioning/platform/orchestrator
|
|
cargo test security_integration_tests
|
|
```plaintext
|
|
|
|
## File Summary
|
|
|
|
| File | Purpose | Lines | Tests |
|
|
|------|---------|-------|-------|
|
|
| `middleware/security_context.rs` | Security context builder | 275 | 8 |
|
|
| `middleware/auth.rs` | JWT authentication | 245 | 5 |
|
|
| `middleware/mfa.rs` | MFA verification | 290 | 15 |
|
|
| `middleware/authz.rs` | Cedar authorization | 380 | 4 |
|
|
| `middleware/rate_limit.rs` | Rate limiting | 420 | 8 |
|
|
| `middleware/mod.rs` | Module exports | 25 | 0 |
|
|
| `security_integration.rs` | Integration helpers | 265 | 2 |
|
|
| `tests/security_integration_tests.rs` | Integration tests | 340 | 11 |
|
|
| **Total** | | **2,240** | **53** |
|
|
|
|
## Benefits
|
|
|
|
### Security
|
|
|
|
- ✅ Complete authentication flow with JWT validation
|
|
- ✅ MFA enforcement for sensitive operations
|
|
- ✅ Fine-grained authorization with Cedar policies
|
|
- ✅ Rate limiting prevents API abuse
|
|
- ✅ Complete audit trail for compliance
|
|
|
|
### Architecture
|
|
|
|
- ✅ Modular middleware design
|
|
- ✅ Clear separation of concerns
|
|
- ✅ Reusable security components
|
|
- ✅ Easy to test and maintain
|
|
- ✅ Configuration-driven behavior
|
|
|
|
### Operations
|
|
|
|
- ✅ Can enable/disable features independently
|
|
- ✅ Development mode for testing
|
|
- ✅ Comprehensive error messages
|
|
- ✅ Real-time statistics and monitoring
|
|
- ✅ Non-blocking audit logging
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Token Refresh**: Automatic token refresh before expiry
|
|
2. **IP Whitelisting**: Additional IP-based access control
|
|
3. **Geolocation**: Block requests from specific countries
|
|
4. **Advanced Rate Limiting**: Per-user, per-endpoint limits
|
|
5. **Session Management**: Track active sessions, force logout
|
|
6. **2FA Integration**: Direct integration with TOTP/SMS providers
|
|
7. **Policy Hot Reload**: Update Cedar policies without restart
|
|
8. **Metrics Dashboard**: Real-time security metrics visualization
|
|
|
|
## Related Documentation
|
|
|
|
- Cedar Policy Language
|
|
- JWT Token Management
|
|
- MFA Setup Guide
|
|
- Audit Log Format
|
|
- Rate Limiting Best Practices
|
|
|
|
## Version History
|
|
|
|
| Version | Date | Changes |
|
|
|---------|------|---------|
|
|
| 1.0.0 | 2025-10-08 | Initial implementation |
|
|
|
|
---
|
|
|
|
**Maintained By**: Security Team
|
|
**Review Cycle**: Quarterly
|
|
**Last Reviewed**: 2025-10-08
|
|
</code></pre>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../architecture/orchestrator_info.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="../architecture/repo-dist-analysis.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/orchestrator_info.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="../architecture/repo-dist-analysis.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>
|
|
|
|
|
|
|
|
|
|
<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>
|