Architecture Security Overview

Version: 1.0 Last Updated: September 2026

---

1. System Architecture

                    Internet
                       |
                  [TLS Termination]
                   nginx + Let's Encrypt
                       |
              [Private Docker Network]
                       |
            +----------+----------+
            |                     |
       [Nova IAM App]      [PostgreSQL 16]
       Gunicorn/Flask        Backend DB
       Port 8000 (internal)  Port 5432 (internal)
            |
            +--- SAP RFC (outbound)
            +--- LDAP/LDAPS (outbound)
            +--- Microsoft Graph API (outbound, HTTPS)
            +--- Ollama (local, optional)
            +--- Cloud AI API (outbound, HTTPS, optional)

2. Security Boundaries

External Boundary (Internet-facing)

• TLS termination at nginx reverse proxy with automated Let's Encrypt certificates
• Only HTTPS (443) exposed to the internet
• HTTP (80) redirects to HTTPS
• Application and database ports are not directly accessible

Internal Boundary (Docker network)

• Application and database communicate over isolated Docker bridge network
• Database port is not published to the host in production
• Backend system connections (SAP, LDAP, Entra) are outbound-only from the application

Application Boundary

• All API requests pass through authentication middleware
• Only /api/login and /api/me are unauthenticated
• Same-origin policy enforced (no CORS headers configured)

3. Authentication Flow

User -> POST /api/login (email, password)
  -> Server: lookup user by email
  -> Server: verify password hash (scrypt/pbkdf2)
  -> Server: create signed session cookie
  -> Server: audit log (login, actor_id, IP)
  -> Response: user profile (no sensitive data)

Subsequent requests:
  -> Middleware: verify session cookie signature
  -> Middleware: extract user_id from session
  -> Route handler: process authenticated request

4. Data Flow — Role Assignment

Admin assigns Business Role to User
  -> API: POST /api/users/{id}/roles
  -> Server: validate business role exists
  -> Server: create user_assignment (type: business_role)
  -> Server: create indirect assignments for member entitlements
  -> Server: check auto-provision setting
  -> If enabled: provision to backend systems
     -> SAP: BAPI_USER_ACTGROUPS_ASSIGN (full sync)
     -> LDAP: group membership add (incremental)
     -> Entra: Graph API group add (incremental)
  -> Server: audit log (role change, actor, target, details)
  -> Response: success + any provisioning warnings

5. Security Controls Matrix

Layer	Control	Implementation
Network	TLS encryption	nginx + Let's Encrypt (TLS 1.2+)
Network	Network isolation	Docker private networks
Network	Port restriction	Only 443 exposed externally
Application	Authentication	Signed server-side sessions
Application	Authorization	Middleware-enforced auth on all API routes
Application	Input validation	Parameterized SQL queries, request body validation
Application	CSRF protection	Same-origin policy (no CORS)
Data	Password protection	scrypt/pbkdf2 hashing with salt
Data	Secrets management	Environment variables, not in codebase
Data	Referential integrity	PostgreSQL foreign key constraints
Audit	Event logging	audit_log with actor, target, IP, timestamp and origin (incl. AI chat)
Audit	No edit or delete function	No UI or API function to edit or delete audit records
Deployment	Automated TLS	Let's Encrypt auto-renewal
Deployment	Health monitoring	Docker healthchecks on database
Deployment	Idempotent migrations	Safe, repeatable schema updates

6. Backend System Connectivity

SAP (RFC)

• Connection via SAP NetWeaver RFC SDK
• Credentials stored in target_systems.config (JSONB, encrypted at rest via PostgreSQL)
• Communication over SAP proprietary protocol (typically on private network)

LDAP

• Supports LDAP and LDAPS (TLS-encrypted)
• Bind credentials stored in target_systems.config
• Certificate validation configurable per connection

Microsoft Entra ID

• OAuth 2.0 client credentials flow
• Communication over HTTPS to Microsoft Graph API
• Client secret stored in target_systems.config

AI Providers (Optional)

• Local (Ollama): HTTP to localhost only, no data leaves the network
• Cloud: HTTPS to provider API (Anthropic/OpenAI), opt-in, disabled by default
• API keys stored in environment variables, not in database

7. Deployment Hardening Checklist

• Set a strong, unique SECRET_KEY environment variable
• Change default database credentials from postgres/postgres
• Enable sslmode=require on database connections
• Verify .env file is excluded from version control
• Configure TLS certificates (automated via Let's Encrypt or manual)
• Restrict database port access to application container only
• Set up regular database backups with encryption
• Enable PostgreSQL log_connections and log_disconnections
• Configure firewall rules to allow only HTTPS (443) inbound
• Review and rotate backend system credentials on deployment
• Disable AI cloud features if data sovereignty is required