bitzorcas
中EN

Concept

Security architecture overview

Understand BitzOrcas defense in depth across authentication, authorization, tenant isolation, request integrity, data protection, and audit.

Last updated

The BitzOrcas security boundary extends beyond login. Before a request reaches a business Handler, it passes transport controls, authentication, tenant resolution, authorization, and audit. Persistence then applies tenant filters, soft-delete behavior, and concurrency checks.

TLS / Forwarded Headers / CORS / Security Headers
                    │
                    ▼
JWT / HMAC / API Key / SCIM Bearer authentication
                    │
                    ▼
current caller → tenant resolution → optional impersonation
                    │
                    ▼
HTTP authorization + Mediator authorization decision
                    │
                    ▼
data scope + ORM tenant filter + audit trail

Transport and browser boundary

Authenticated principal

Trusted tenant

Resource authorization and data scope

Persistence isolation and audit

Security capabilities

TopicQuestion answered
AuthenticationHow users, application callers, and SCIM provisioners prove identity
AuthorizationHow RBAC, App Scope, ABAC, ReBAC, and Feature decisions combine
CORS and security headersBrowser origins, proxies, and response-header boundaries
Operator impersonationTime-bounded, audited Host impersonation of users or tenants
Webhook signingIntegrity and replay defense for inbound/outbound webhooks
Two-factor authenticationTOTP, FIDO2, recovery codes, and trusted devices
Data protectionKey persistence, sensitive configuration, and data-at-rest protection
Production checklistConfiguration, key, network, and operations evidence before release

Five boundary rules

Authentication establishes identity only

A valid JWT or matching API Key does not permit every action. Authentication builds CurrentUser with caller type, tenant, roles, permissions, or scopes. Authorization then evaluates the target resource and action.

A client cannot choose its tenant

tenant_id comes from a trusted claim, application credential, Host mapping, or controlled job scope. Headers and paths can only confirm an already-authenticated tenant. See Multitenancy deep dive.

Deny wins; absence of allow also denies

Any policy Deny blocks the request. No matching Allow also blocks it. A dependency failure must never become permission.

Secrets have no weak defaults

Missing JWT issuer, audience, or signing material stops startup. API Keys and SCIM tokens remain SHA-256 hashes at runtime. HMAC secrets still require managed configuration plus client-specific rotation and revocation.

Security operations remain traceable

Authentication failures, authorization decisions, impersonation, sensitive operations, key management, and exceptions need tenant, actual operator, CorrelationId, and TraceId. Logs never include credential plaintext.

Threats and defenses

ThreatMain defenseRequired operations control
Stolen JWTShort lifetime, issuer/audience, zero ClockSkew, kid rotationTLS, revocation policy, endpoint security
HMAC replayTimestamp, nonce, method/path/query/body-hash signatureShared Redis nonce store, secret rotation
Leaked API KeyHash lookup, fixed-time comparison, tenant/scope bindingShow once, revoke, least scope
Cross-tenant accessTrusted resolution, resource authorization, ORM filterPrimary-key/bulk/complex-query contract tests
Missing permission configurationDeny precedence, no-Allow denial, unavailable adaptersReadiness, alerting, audit monitoring
Browser cross-origin callsToken auth, CORS, security headersExact origin list, TLS, frontend storage policy

When developing a feature

  1. Declare resource and action on the Command/Query instead of scattering checks in the Handler.
  2. Obtain caller and tenant from trusted context, not ownership fields in a DTO.
  3. Apply DataScope to list reads in addition to the ORM tenant filter.
  4. Define redaction for secrets, tokens, personal data, and sensitive business fields.
  5. Test anonymous, denied, cross-tenant, expired-impersonation, unavailable-dependency, and cache-invalidation paths.

How to read this section

Start with authentication and authorization to establish caller, resource, and action semantics, then study the browser/proxy boundary and Data Protection. Use the delegation, MFA, and Webhook chapters for those flows, and finish with the production evidence checklist. Every page distinguishes shipped primitives, Host composition responsibility, and work an adopting business module must still complete.

100%

Scroll or use controls to zoom · drag when enlarged · double-click for 100% / 200%