Skip to content

Security

Target Architecture — Final-State Design

This page describes the final-state security model of the Integration Platform. Because this platform is the factory's boundary to untrusted external systems, it carries the highest concentration of secret material and inbound attack surface — and is correspondingly the most tightly governed. Secrets live only in Azure Key Vault; nothing sensitive is ever persisted, logged, or placed in an event payload.

The Integration Platform sits at the edge, so its security posture defends two directions at once: outbound, it holds the credentials that let the factory act on external systems; inbound, it is the front door for webhooks from systems the factory does not control. Every control below ladders up to the factory pillars of governance, traceability, and multi-tenant isolation, and integrates with the Governance, Security & Compliance Platform.

Authentication

  • Service callers authenticate with OAuth2 client-credentials tokens issued by the factory identity provider; tokens carry tenantId and scope claims.
  • Factory Studio users authenticate with OAuth2 authorization-code + PKCE; the backend-for-frontend exchanges and never exposes tokens to the browser.
  • Vendor-facing auth uses ConnectSoft.Extensions.Http.OAuth2 to manage client-credentials and authorization-code token lifecycles for external APIs, refreshing transparently.
  • Workload identity — services authenticate to Key Vault and Azure resources via Managed Identity, eliminating bootstrap secrets.

Authorization

  • Scope- and role-based authorization on every endpoint. Representative scopes: integration.connections.write/read, integration.providers.write, webhooks.subscriptions.write, webhooks.deliveries.ingest, integration.runs.read, integration.credentials.rotate.
  • Least privilege per service. Each integration service is granted only the Key Vault entries and provider scopes it needs; the VendorApiClientRegistryService alone holds credential-rotation rights.
  • Sensitive actions are gated. Establishing connections, rotating credentials, and replaying deliveries require elevated scopes and emit audited events.

Tenant Isolation

  • tenantId is a mandatory claim and predicate on every store access, Key Vault namespace, and Blob container.
  • No query path spans tenants; provider/API-client catalogue rows may be global (read-only) but connections, credentials, and deliveries are always tenant-owned.
  • Rate-limit buckets and circuit-breaker state are partitioned by tenant so one tenant cannot exhaust another's vendor budget.

Secret Handling

This is the platform's defining control.

  • Key Vault is the only secret store. All API keys, OAuth2 client secrets, signing secrets, and tokens live in Azure Key Vault. Aggregates store only keyVaultRef plus a non-reversible SecretFingerprint.
  • Plaintext-free guarantee. Secrets are resolved transiently at call time, used in-memory, and never written to a database, log line, trace attribute, or event payload.
  • OAuth2 lifecycle. ConnectSoft.Extensions.Http.OAuth2 acquires, caches in-memory, and refreshes vendor tokens; refresh tokens are stored only as Key Vault references.
  • Rotation by default. The CredentialRotationWorker rotates secrets on policy or demand, keeping the prior version active until the new one passes a verification run (see Workflows).
  • Soft-delete + purge protection on Key Vault; rotation retains prior versions for rollback.

Webhook Security (Inbound)

  • Signature verification. Every inbound delivery is verified against the provider's signature scheme (HMAC-SHA256 / JWS) using a per-subscription signing secret from Key Vault before any processing.
  • Tenant resolution. The owning tenantId is resolved from the verified subscription, never from untrusted payload fields.
  • Replay protection. Deliveries are idempotent on providerDeliveryId; timestamps and nonces guard against replay.
  • SSRF defense (outbound). Subscription endpoints must be HTTPS and pass an allow-list / private-IP-block check before any delivery; raw payloads are size-capped.

Audit

  • Every connection lifecycle change, credential rotation, webhook subscription, and delivery replay emits a canonical event carrying operator identity and traceId.
  • CredentialRotated, WebhookSubscribed, and IntegrationFailed (auth) flow to the Governance, Security & Compliance Platform for the immutable audit trail.
  • Access to credential metadata and payload bodies is logged with subject, action, and resource.

Threats & Mitigations

Threat Mitigation
Credential leakage Key Vault-only storage; plaintext-free guarantee; fingerprints in logs
Stolen/long-lived secrets Automated rotation; short-lived OAuth2 tokens; Managed Identity
Forged inbound webhooks Mandatory signature verification + per-subscription secret + replay protection
SSRF via outbound endpoints HTTPS-only + allow-list + private-IP block on subscription endpoints
Cross-tenant access tenantId predicate on every store/secret/blob access; partitioned buckets
Vendor abuse / runaway cost Per-tenant rate limits, circuit breakers, and quota enforcement
Poison/malicious payloads Size caps, schema validation, dead-letter isolation with preserved envelope
Privilege escalation Least-privilege scopes; rotation rights confined to the registry service

Credential Governance

Credentials are governed as first-class assets, not configuration:

  • Ownership & classification. Each IntegrationCredential has a tenant owner and sensitivity classification applied by Governance.
  • Lifecycle policy. Rotation cadence, expiry, and revocation rules are policy-driven and enforced by the CredentialRotationWorker.
  • Revocation. Compromised credentials are revoked centrally; dependent connections move to Degraded and stop executing runs until re-credentialed.
  • Separation of duties. The service that uses a credential is distinct from the registry service that custodies and rotates it.