diff --git a/auth/authenication.md b/auth/authenication.md new file mode 100644 index 0000000..074b84b --- /dev/null +++ b/auth/authenication.md @@ -0,0 +1,218 @@ +# 🔐 ComplyCore Authentication & Authorization Design + +**Component:** Identity & Access Management (IAM) +**Version:** v1.0 +**Last Updated:** 2024-07-11 +**Owner:** Kell Engineering + +--- + +## ✅ Overview + +ComplyCore uses a **multi-tenant, RBAC-enforced identity system** built on PostgreSQL with Supabase Auth. All user and system access is governed by: + +- **Tenant isolation** via Row-Level Security (RLS) +- **Role-Based Access Control (RBAC)** via ENUM roles +- **Session-scoped variables** (`set_config()`) instead of legacy JWT hooks +- **Support for both human users and non-person entities (NPEs)** +- **Audit logging** for access, evaluation, and data modification events + +--- + +## 🧱 Database Entity Model + +```mermaid +erDiagram + tenants ||--o{ users : has + tenants ||--o{ api_clients : owns + tenants ||--o{ evaluations : owns + users ||--o{ evaluations : creates + users ||--o{ auth_audit_log : actor + api_clients ||--o{ auth_audit_log : actor + + tenants { + UUID id PK + TEXT name + TEXT cage_code + TEXT sam_uid + } + + users { + UUID id PK + UUID tenant_id FK + TEXT first_name + TEXT last_name + TEXT email + user_role role + } + + api_clients { + UUID id PK + UUID tenant_id FK + TEXT client_id + TEXT client_secret + api_scope[] scopes + } + + evaluations { + UUID id PK + UUID tenant_id FK + TEXT control_id + TEXT status + } + + auth_audit_log { + UUID id PK + UUID actor_id + UUID tenant_id FK + TEXT action + TEXT result + } +``` + +--- + +## 👤 User Roles + +```mermaid +flowchart LR + A[client_user] -->|RLS: Own tenant only| EvalTable + B[client_admin] -->|RLS: Own tenant only + mgmt| EvalTable + C[reviewer] -->|RLS: Read all tenants| EvalTable + D[superadmin] -->|RLS: Full control| EvalTable & UserTable +``` + +| Role | Description | Access Scope | +|--------------|----------------------------------|----------------------| +| `client_user`| End user | Own tenant only | +| `client_admin`| Tenant admin | Own tenant (plus user mgmt) | +| `reviewer` | Internal auditor or compliance | All tenants (read-only) | +| `superadmin` | Platform operator | Full access to all data | + +--- + +## 🔐 RLS Policies + +| Table | Role(s) | Access Type | Rule Description | +|------------------|----------------------|-----------------|--------------------------------------------| +| `users` | All | Self only | `id = auth.uid()` | +| `evaluations` | `client_*` | Tenant-bound | Match tenant via `set_config()` | +| `evaluations` | `reviewer` | Global read | Unrestricted SELECT | +| `evaluations` | `superadmin` | Full access | Unrestricted ALL w/ check | +| `api_clients` | All | Own tenant only | `enabled=true` AND tenant match | +| `auth_audit_log` | All | Tenant-bound | Match tenant | + +--- + +## 🔑 Session Variables (No JWT Custom Claims) + +Instead of deprecated JWT claim injection, ComplyCore uses: + +```sql +SELECT set_config('request.jwt.claim.role', user.role, true); +SELECT set_config('request.jwt.claim.tenant_id', user.tenant_id::text, true); +``` + +This enables per-session RLS enforcement and simplifies system-wide access control. + +--- + +## 🛡️ NPE: Non-Person Entities (API Clients) + +**Table:** `api_clients` + +| Field | Purpose | +|---------------|----------------------------------| +| `client_id` | Public API token ID | +| `client_secret` | Auth key (hashed) | +| `tenant_id` | Enforces scope per client | +| `scopes[]` | Least-privilege operations | +| `enabled` | Soft-delete / disable mechanism | + +**Scopes Enum:** +- `upload` +- `evaluate` +- `read_reports` +- `manage_projects` + +> RLS prevents disabled clients or cross-tenant access. + +--- + +## 📝 Audit Logging + +**Table:** `auth_audit_log` + +| Field | Type | Description | +|---------------|------------|----------------------------------------------| +| `actor_id` | UUID | User or service account | +| `tenant_id` | UUID | Organization context | +| `action` | TEXT | Description (e.g., `login_success`) | +| `target_table`| TEXT | Optional: table affected | +| `result` | TEXT | `success` or `fail` | +| `timestamp` | TIMESTAMP | System-generated UTC timestamp | + +This log supports: +- Login tracking +- API usage validation +- Internal audit trail for CMMC/DFARS controls + +--- + +## 🧠 CMMC Practice Coverage + +| Practice | Control Area | Implementation | +|----------------------|-----------------------|----------------------------------------| +| AC.1.001 | Access Control | Unique accounts (auth.users + users) | +| AC.1.002 | Access Enforcement | RBAC and RLS | +| AC.1.003 | Least Privilege | Role + tenant-scoped access | +| AU.2.042 | Audit Logs | `auth_audit_log` | +| IA.2.078 | MFA Capable | `mfa_enabled` flag (enforced by UI) | +| SC.3.177 | NPE Separation | `api_clients` with isolated scopes | + +--- + +## 📎 Appendices + +### 🔧 Initial Setup Function + +```sql +CREATE OR REPLACE FUNCTION set_claim_context() +RETURNS void +LANGUAGE plpgsql +SECURITY DEFINER +AS $$ +DECLARE + v_role TEXT; + v_tenant UUID; +BEGIN + SELECT role, tenant_id INTO v_role, v_tenant + FROM public.users + WHERE id = auth.uid(); + + PERFORM set_config('request.jwt.claim.role', v_role, true); + PERFORM set_config('request.jwt.claim.tenant_id', v_tenant::text, true); +END; +$$; +``` + +Call this at the start of every request/session to enforce scoped access. + +--- + +## ✅ Status + +| Component | Status | Notes | +|--------------------|---------------|----------------------------------------| +| Supabase Auth | ✅ Integrated | Used for identity backing | +| Postgres Tables | ✅ Complete | tenants, users, api_clients, audits | +| RLS Policies | ✅ Enforced | All core tables | +| Session Claims | ✅ Supported | Via `set_config()` | +| MFA Support | 🟡 Flagged | Client-side UI pending | + +--- + +**Maintained by:** Kell Engineering +**Contact:** mtkell@kellengineering.com +**Document ID:** `AUTH-DOC-001` +