Skip to content

Security Implementation Standard

Purpose

The Security Implementation Standard defines backend security implementation guidance for Keycloak, Spring Security, Identity authorization, Billing entitlements, tenant isolation, and audit.

Security Flow

sequenceDiagram
    participant Client
    participant SpringSecurity as Spring Security
    participant Identity
    participant Billing
    participant App as Application Service

    Client->>SpringSecurity: Request with Keycloak JWT
    SpringSecurity->>SpringSecurity: Validate token
    SpringSecurity->>Identity: Resolve actor and tenant access
    Identity-->>SpringSecurity: Authorization context
    SpringSecurity->>Billing: Check entitlement where required
    SpringSecurity->>App: Execute with secure context

Rules

  • Keycloak is the official identity provider.
  • Spring Security validates JWT access tokens before business work.
  • Identity owns business authorization decisions.
  • Billing owns entitlement and usage-limit decisions.
  • Tenant and OrganizationId context must be established before repository access.
  • High-impact actions may require MFA, approval, or additional policy checks.
  • AIOS tool calls use governed internal identities and are auditable.
  • Integration credentials are separate from user-session credentials.
  • All denials fail closed and use standard API errors.

Implementation Boundaries

Concern Owner
Token validation Spring Security and Keycloak integration.
Membership and authorization Identity module.
Entitlements Billing module.
Tenant-scoped data access Owning module repositories.
Security audit Owning module plus audit governance.

Forbidden Patterns

  • Trusting client-provided tenant context without verification.
  • Authorizing from token claims alone.
  • Storing secrets or tokens in logs.
  • Allowing AIOS or services to bypass application services.
  • Returning stack traces or policy internals in errors.