Authorization Architecture

Executive Summary

Authorization Architecture defines how Algosure decides whether authenticated users, AIOS tools, services, and integrations may perform actions or access data. Authorization is owned by the Identity Domain and enforced across secure APIs, application services, and domain workflows.

Why This Exists

Authentication identifies the caller. Authorization decides whether the caller can act in a specific tenant, organization, Domain, workflow, document, integration, or AIOS context.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Clear authorization prevents privilege escalation, cross-tenant access, unauthorized document exposure, unapproved AI actions, and commercial entitlement bypass.

Authorization Model

flowchart TB
    Actor[Authenticated Actor]
    Tenant[Tenant Context]
    Organization[Organization Context]
    RBAC[RBAC: Roles and Permissions]
    ABAC[Future ABAC: Attributes and Policies]
    Entitlement[Billing Entitlement]
    Approval[Approval Control]
    Decision[Authorization Decision]
    Domain[Owning Domain Action]

    Actor --> Tenant
    Tenant --> Organization
    Organization --> RBAC
    RBAC --> ABAC
    ABAC --> Entitlement
    Entitlement --> Approval
    Approval --> Decision
    Decision --> Domain

Authorization Inputs

Input	Source Owner
User identity	Identity Domain.
Roles and permissions	Identity Domain, with Keycloak as identity platform support.
Groups	Keycloak platform construct interpreted by Identity Domain.
Tenant access	Identity Domain with Organization context.
Organization membership	Organization Domain.
Entitlements and limits	Billing Domain.
Feature flags and platform policy	Administration Domain.
Domain-specific state	Owning Domain.
Approval requirements	Owning workflow, Domain, and Administration policy.

Keycloak Mapping Model

Keycloak roles, groups, and claims are authentication platform signals. The Identity Domain maps those signals into Algosure authorization context.

Keycloak Signal	Algosure Interpretation
Realm roles	Platform-level role signals that may map to Algosure roles or administrative privileges.
Client roles	Application-specific role signals that may map to API access scopes or client-specific capabilities.
Groups	Enterprise, organization, team, or department grouping signals that must be mapped to Organization and Identity concepts before authorization.
Token claims	Authentication context and hints that require validation and domain resolution before use.
Service account identity	Machine actor identity that maps to least-privilege internal permissions and audit context.

Organization and Tenant Mapping

Mapping Concern	Architecture Rule
Tenant ID	May be carried as a trusted mapped claim or resolved from Identity and Organization records, but tenant access is owned by Identity with Organization context.
Organization ID	May be mapped from group, attribute, or Identity/Organization records, but Organization owns organization facts.
Membership	Organization membership is not assumed from a token alone; it must resolve against Identity and Organization rules.
Multi-organization users	Users may have access to multiple organizations; API requests must resolve the active organization context explicitly.
Cross-tenant administration	Platform administration access requires explicit privileged role, MFA, least privilege, policy checks, and audit.

API Authorization Flow

sequenceDiagram
    participant Client as API Consumer
    participant API as Spring Security API Boundary
    participant Keycloak as Keycloak
    participant Identity as Identity Domain
    participant Organization as Organization Domain
    participant Billing as Billing Domain
    participant Domain as Owning Domain

    Client->>API: Request with JWT access token
    API->>Keycloak: Validate issuer, signature, audience, expiry
    API->>Identity: Resolve user, roles, permissions, tenant access
    Identity->>Organization: Resolve organization membership and context
    Identity->>Billing: Resolve entitlement context where required
    Identity-->>API: Authorization context
    API->>Domain: Execute if authorized and entitled

Authorization Rules

Rule	Requirement
RBAC is the baseline	Role and permission checks are the initial authorization model.
Future ABAC is reserved	Attribute-based authorization may be added for contextual policies when justified.
Authorization is contextual	Tenant, organization, user, role, permission, entitlement, workflow state, and action all matter.
Fail closed	Missing, ambiguous, expired, or conflicting authorization context denies access.
Domain rules apply	Generic permission is not enough when the owning Domain has state-specific rules.
Entitlements are enforced	Billing-owned plan, feature, and limit checks gate entitlement-controlled capabilities.
High-impact actions require approval	Submissions, payments, funding, AI-generated commitments, and sensitive external actions require approval where policy requires it.
Authorization is auditable	Decisions, denials, overrides, and approvals must be traceable.
Keycloak roles are not enough	Keycloak role membership must be interpreted by Identity and combined with tenant, organization, entitlement, and Domain policy.
Service accounts are least-privilege	Internal service access must use scoped permissions, short-lived credentials where practical, and audit.

AIOS Authorization

AIOS access must be governed like a privileged internal consumer.

Rule	Meaning
AIOS uses governed internal APIs	AIOS must not directly access repositories, databases, object storage, or secrets.
AIOS receives scoped permissions	Tool calls are limited to task, tenant, organization, Domain, and approved capability.
AIOS outputs are not self-authorizing	Recommendations and drafts require owning Domain acceptance and approval where required.
AIOS access is auditable	Tool calls, context access, generated outputs, and decisions are logged.

Non-Implementation Boundary

This document does not define permission names, role catalogues, policy language, ABAC engine, Keycloak role mapping, or code-level authorization checks.