Authentication Architecture

Executive Summary

Authentication Architecture defines how Algosure establishes caller identity. Keycloak is the official Identity Provider for authentication, SSO, realms, clients, roles, groups, token issuing, MFA, and federation.

Why This Exists

Algosure requires enterprise-grade authentication across mobile, web, internal APIs, AIOS tool calls, and integrations. Authentication must integrate with Keycloak while preserving Identity Domain ownership of business identity and authorization decisions.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Strong authentication reduces account compromise risk, supports enterprise SSO, enables MFA, and provides consistent identity context for authorization and audit.

Authentication Flow

sequenceDiagram
    participant User as User
    participant Client as Mobile or Web App
    participant Keycloak as Keycloak Identity Provider
    participant API as Algosure API Boundary
    participant Identity as Identity Domain
    participant Domain as Owning Domain

    User->>Client: Start sign-in
    Client->>Keycloak: Authenticate with SSO, MFA, or federation
    Keycloak-->>Client: Issue token
    Client->>API: Request with token
    API->>Keycloak: Validate token trust
    API->>Identity: Resolve Algosure identity and access context
    Identity-->>API: User, roles, permissions, membership context
    API->>Domain: Continue authorized request

Keycloak Responsibilities

Responsibility	Meaning
Authentication	Establish user identity through configured login flows.
SSO	Support single sign-on across approved clients.
Realms and clients	Provide authentication boundary configuration for Algosure environments and applications.
Token issuing	Issue tokens for authenticated sessions and clients.
MFA	Enforce multi-factor authentication where policy requires it.
Federation	Integrate with external enterprise identity sources where approved.
Roles and groups	Provide platform-level identity constructs consumed by Algosure authorization logic.

Realm Strategy

Algosure uses Keycloak as the official Identity Provider. Realm strategy is an authentication architecture concern, not the source of business tenant ownership.

Realm Concern	Architecture Rule
Algosure realm	The Algosure realm is the primary authentication boundary for platform users, clients, service accounts, token issuing, MFA, SSO, and federation.
Environment separation	Non-production and production authentication boundaries must be separated.
Tenant representation	Customer tenant and organization context may be represented through mapped claims, groups, or attributes, but Organization remains the source of organization facts.
Federation	Enterprise identity federation is configured through Keycloak but governed by Identity, Organization, security, and tenant policy.
Social login	Future social login may be enabled only where customer segment, risk, and policy justify it.

Client Architecture

Client	Keycloak Client Role
Mobile app	Public client using an approved mobile authentication flow, short-lived access tokens, refresh tokens where policy allows, and no embedded client secret.
Web app	Public or confidential client depending on final web architecture; browser-facing flows must protect tokens and prevent client-side secret exposure.
Spring Boot Modulith backend	Resource server that validates JWT access tokens and enforces authenticated API access through Spring Security.
Internal services	Confidential clients or service accounts for machine-to-machine access under least privilege and audit.
Integration gateway	Uses service identity where Algosure calls external systems and separates external provider credentials from user authentication.

Token Architecture

Token Type	Architecture Rule
JWT access token	Used for API access and validated by the backend before business work.
Refresh token	Used only by approved clients to obtain new access tokens under rotation, expiry, revocation, and session risk policy.
Service account token	Used for internal service-to-service authentication with scoped permissions and audit.
Token claims	Claims may carry subject, issuer, audience, expiry, roles, groups, tenant hints, organization hints, and correlation context where approved.
Token limits	Tokens establish authentication context; they do not replace Identity, Organization, Billing, or Domain authorization decisions.

Spring Security Validation

The Spring Boot Modulith backend validates Keycloak-issued JWT access tokens through Spring Security before resolving Algosure authorization context.

Validation Step	Requirement
Issuer validation	Token issuer must match the trusted Keycloak realm.
Signature validation	Token signature must be valid against trusted Keycloak keys.
Audience validation	Token audience must match the intended Algosure API or service.
Expiry validation	Expired tokens are rejected.
Role and group extraction	Roles and groups are extracted as authentication inputs, not final business authority.
Context resolution	Identity resolves user, tenant access, organization membership, permissions, and audit context.

Future Login Options

Option	Architecture Position
Enterprise SSO	Supported through Keycloak federation when tenant governance, claim mapping, and support ownership are defined.
Social login	Future capability only for approved user segments and risk profiles.
Passwordless login	Future capability subject to MFA, recovery, device, and fraud-risk review.

Identity Domain Responsibilities

Responsibility	Meaning
Business identity model	Owns users, memberships, tenant access, permissions, and authorization context.
Authorization decisions	Interprets roles, permissions, memberships, tenant access, and policy for Algosure.
Audit context	Supplies user and actor context for audit records.
Organization relationship	Coordinates with Organization for organization membership and tenant alignment.

Authentication Rules

Rule	Requirement
Authentication is mandatory	No customer-data API may execute without authenticated identity or approved service identity.
Tokens are not business authority alone	Tokens establish authentication; Algosure still resolves Identity, Organization, permission, and entitlement context.
MFA for sensitive access	Administrative, privileged, and high-impact workflows require MFA where policy requires it.
Federation is governed	External identity federation requires security and tenant governance review.
Sessions are auditable	Login, logout, token failures, MFA events, and suspicious access must be auditable.
Integration identities are separate	Service accounts and integration clients must be scoped, least-privilege, and auditable.

Non-Implementation Boundary

This document does not define Keycloak realm names, client configuration, token claims, protocol settings, MFA policy syntax, or federation setup.