Updated directory structure. Initial authnication design and database initialization files.
This commit is contained in:
parent
22d200451a
commit
82d6ae8f57
|
|
@ -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`
|
||||||
|
|
||||||
Loading…
Reference in New Issue