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