Skip to content
Abyxon Abyxon

Auth Module Architecture

OctoFHIR Auth Module Architecture

Section titled “OctoFHIR Auth Module Architecture”

Executive Summary

Section titled “Executive Summary”

This document presents a comprehensive architectural plan for the OctoFHIR Auth module—a production-grade authentication, authorization, and access control system designed for a modern FHIR R4/R5 server in Rust. The architecture supports:

  • Built-in OAuth 2.0 Server with authorization code, client credentials, and refresh token flows
  • External Identity Provider Federation via OpenID Connect
  • Full SMART on FHIR Compliance (STU 2.2) including App Launch and Backend Services
  • Custom FHIR Resources for auth configuration via internal Implementation Guide
  • AccessPolicy Engine with pattern matching and scriptable policies (QuickJS)

Table of Contents

Section titled “Table of Contents”
  1. Design Principles
  2. High-Level Architecture
  3. Component Deep Dives
  4. Custom FHIR Resources (IG)
  5. Data Models
  6. API Endpoints
  7. Security Considerations
  8. Integration Points
  9. Configuration
  10. Implementation Roadmap

1. Design Principles

Section titled “1. Design Principles”

1.1 Core Tenets

Section titled “1.1 Core Tenets”
PrincipleDescription
Zero TrustEvery request is authenticated and authorized; no implicit trust
Defense in DepthMultiple security layers (transport, token, policy, audit)
Standards ComplianceFull FHIR R4/R5, OAuth 2.0, OpenID Connect, SMART on FHIR STU 2.2
ExtensibilityPlugin architecture for custom policies and identity providers
PerformanceSub-millisecond policy evaluation; async-first design
PersistenceNo in-memory-only state; all auth data in PostgreSQL

1.2 Architectural Constraints

Section titled “1.2 Architectural Constraints”
  • No In-Memory Storage: All session state, tokens, and policies stored in PostgreSQL
  • Horizontal Scalability: Stateless request handling; shared database state
  • Hot Reload: Policy and configuration changes without server restart
  • Audit Everything: Security-relevant events logged as FHIR AuditEvent resources
  • Alpine Linux Compatible: All components must work with musl libc

2. High-Level Architecture

Section titled “2. High-Level Architecture”
┌─────────────────────────────────────────────────────────────────────────────┐
│                              OctoFHIR Server                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Axum      │  │  Content    │  │   Auth      │  │    FHIR Resource    │ │
│  │  Router     │──│ Negotiation │──│ Middleware  │──│     Handlers        │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│         │                                │                     │            │
│         ▼                                ▼                     ▼            │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                         Auth Module (octofhir-auth)                     ││
│  ├─────────────────────────────────────────────────────────────────────────┤│
│  │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐               ││
│  │  │ OAuth 2.0     │  │  SMART on     │  │   Identity    │               ││
│  │  │ Server        │  │  FHIR         │  │   Federation  │               ││
│  │  │               │  │               │  │               │               ││
│  │  │ • /authorize  │  │ • Scopes      │  │ • OIDC Client │               ││
│  │  │ • /token      │  │ • Launch Ctx  │  │ • JWKS Cache  │               ││
│  │  │ • /revoke     │  │ • Discovery   │  │ • User Sync   │               ││
│  │  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘               ││
│  │          │                  │                  │                        ││
│  │          ▼                  ▼                  ▼                        ││
│  │  ┌─────────────────────────────────────────────────────────────────┐   ││
│  │  │                     Token Service                                │   ││
│  │  │  • JWT Generation (RS256/RS384/ES384)                           │   ││
│  │  │  • Token Validation & Introspection                             │   ││
│  │  │  • Refresh Token Management                                      │   ││
│  │  │  • PKCE Verification                                             │   ││
│  │  └─────────────────────────┬───────────────────────────────────────┘   ││
│  │                            │                                            ││
│  │                            ▼                                            ││
│  │  ┌─────────────────────────────────────────────────────────────────┐   ││
│  │  │                   AccessPolicy Engine                            │   ││
│  │  │  ┌─────────────┐  ┌─────────────────────────┐                   │   ││
│  │  │  │  Pattern    │  │  QuickJS (rquickjs)     │                   │   ││
│  │  │  │  Matcher    │  │  JavaScript Runtime     │                   │   ││
│  │  │  └─────────────┘  └─────────────────────────┘                   │   ││
│  │  └─────────────────────────┬───────────────────────────────────────┘   ││
│  │                            │                                            ││
│  │                            ▼                                            ││
│  │  ┌─────────────────────────────────────────────────────────────────┐   ││
│  │  │                     Audit Service                                │   ││
│  │  │  • AuditEvent Generation (FHIR R4)                              │   ││
│  │  │  • Security Event Logging                                        │   ││
│  │  │  • Compliance Reporting                                          │   ││
│  │  └─────────────────────────────────────────────────────────────────┘   ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                                      │                                      │
│                                      ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                     PostgreSQL (octofhir_auth Schema)                   ││
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           ││
│  │  │ Client  │ │ Session │ │  Token  │ │ Access  │ │  Audit  │           ││
│  │  │         │ │         │ │         │ │ Policy  │ │  Event  │           ││
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘

For the complete architectural details including component deep dives, data models, API endpoints, security considerations, and implementation roadmap, please refer to the original architecture document in the repository.

Key Features

Section titled “Key Features”

OAuth 2.0 Authorization Server

Section titled “OAuth 2.0 Authorization Server”
  • Authorization Code Flow with PKCE (RFC 6749, RFC 7636)
  • Client Credentials Flow for backend services (RFC 6749)
  • Refresh Token Flow for token renewal (RFC 6749)
  • Token introspection (RFC 7662) and revocation (RFC 7009)

SMART on FHIR Compliance

Section titled “SMART on FHIR Compliance”
  • Full SMART v2 scope support (patient/*.rs, user/*.cruds, system/*.rs)
  • EHR launch and standalone launch patterns
  • Patient and encounter context propagation
  • OpenID Connect integration for identity

Token Service

Section titled “Token Service”
  • JWT generation with RS256, RS384, and ES384 algorithms
  • Configurable token lifetimes
  • PKCE (Proof Key for Code Exchange) support
  • Token validation and introspection

AccessPolicy Engine

Section titled “AccessPolicy Engine”
  • Pattern-based access control matching
  • Scriptable policies using QuickJS
  • Resource-level and field-level filtering
  • Sub-millisecond policy evaluation

Identity Provider Federation

Section titled “Identity Provider Federation”
  • OpenID Connect client for external IdPs
  • JWKS caching for efficient key validation
  • User provisioning and synchronization
  • Configurable user attribute mapping

Audit and Compliance

Section titled “Audit and Compliance”
  • FHIR AuditEvent generation for all security-relevant events
  • Comprehensive security event logging
  • Compliance reporting capabilities

Configuration

Section titled “Configuration”

All authentication and authorization settings are configured in octofhir.toml under the [auth] section:

[auth]
enabled = true
issuer = "http://localhost:8888"


[auth.oauth]
access_token_lifetime = "1h"
refresh_token_lifetime = "90d"
grant_types = ["authorization_code", "client_credentials", "refresh_token"]


[auth.signing]
algorithm = "RS384"
key_rotation_days = 90


[auth.smart]
launch_ehr_enabled = true
launch_standalone_enabled = true
public_clients_allowed = true
openid_enabled = true


[auth.policy]
engine = "quickjs"
policy_reload_interval = "60s"


[auth.federation]
# External IdP configuration
[[auth.federation.providers]]
id = "keycloak"
name = "Keycloak SSO"
issuer = "https://keycloak.example.com/realms/myrealm"

See Authentication for user-facing documentation and JWT Key Persistence for production deployment guidance.

Section titled “Related Documentation”