Authentication and Authorization in the Helios FHIR Server

[smunini]

Introduction

The question of who can access healthcare data - and under what conditions - has never been more consequential. The same AI-driven forces that are reshaping clinical workflows are also multiplying the number of systems that need programmatic access to FHIR APIs. Analytics pipelines, population health platforms, clinical decision support engines, data integration services - all of them need to connect to FHIR servers without a human user in the loop. Getting authentication and authorization right for these machine-to-machine scenarios is foundational work that every other capability in the Helios FHIR Server will depend on.

This document shares my thoughts on how to approach authentication and authorization for the Helios FHIR Server. Like the persistence layer discussion, this is an architectural strategy document rather than a comprehensive specification. It explains the main motivating direction, the key building blocks, and the Rust trait designs that will form the backbone of our security model.

Who should read this? Anyone with an interest in FHIR security, healthcare interoperability standards, or Rust-based systems design. Feedback is very much welcome - this is open source, developed in the open, and your perspective matters.

---

The Lay of the Land: What FHIR Says About Security

FHIR itself is not a security protocol. The specification is explicit about this: it defines exchange protocols and data models that must be combined with security protocols defined elsewhere. What FHIR does provide is a clear list of concerns that any production deployment must address - authentication, authorization, audit logging, communications security, and more.

For the Helios FHIR Server, the two most immediate concerns are:

1. Authentication: verifying that a client is who it claims to be
2. Authorization: determining what that authenticated client is allowed to do

The FHIR security specification recommends OAuth 2.0 as the foundational protocol, and for our use cases specifically points to the SMART App Launch Implementation Guide from HL7. SMART provides two distinct authorization patterns: one for user-facing applications (the "App Launch" flow, which involves a human granting consent), and one for backend services operating without a user (the "Backend Services" flow).

Since the Helios FHIR Server does not yet have a UI, our immediate focus is the SMART Backend Services profile - server-to-server, machine-to-machine authorization. The App Launch profile is explicitly out of scope for this first iteration, though our design should accommodate it cleanly in the future. We will add additional design elements in a comment below in this discussion document when that capability is needed, so stay tuned.

---

SMART Backend Services: The Essential Flow

Before jumping into Rust traits, it is worth understanding what the SMART Backend Services protocol actually does. Compared to user-facing OAuth flows, it is refreshingly straightforward.

The core use cases are exactly the kind of systems that benefit from a high-performance Rust FHIR server:

• An analytics platform running nightly bulk data exports from an EHR
• A lab monitoring service checking newly admitted patients and generating alerts
• A data integration service synchronizing newly registered patients with an external database
• A utilization tracking system polling for bed availability every minute

None of these involve a user clicking "Allow". Instead, a system administrator configures the trust relationship out-of-band, and the client then autonomously acquires short-lived access tokens to do its work.

The Protocol in Plain Language

Registration (one-time, out-of-band)

Before anything else, the backend client registers with the FHIR authorization server. The most important part of registration is communicating the client's public key. SMART strongly prefers that this be done by pointing to a URL where the client hosts its JSON Web Key Set (JWKS) - this allows key rotation without re-registering. Embedding the key directly is supported but discouraged. At the end of registration, the server assigns the client a client_id.

Discovery

The client fetches /.well-known/smart-configuration from the FHIR server's base URL to learn the token endpoint URL and the server's capabilities. This is a simple HTTP GET that returns a JSON document.

Token Request

When the client needs to access data, it constructs a one-time-use JWT (a "client assertion") signed with its private key, then POSTs it to the token endpoint. The server validates the JWT signature against the registered public key, checks that the jti (JWT ID) hasn't been replayed, and - if everything checks out - issues a short-lived access token. The spec recommends a maximum lifetime of 5 minutes for these tokens.

API Access

The client presents the access token as a Bearer token in the Authorization header on every FHIR API request. The resource server validates the token and enforces the scopes it carries.

Here is the full flow as a sequence:

Client                    Authorization Server            Resource Server
  |                               |                              |
  |-- POST /token                 |                              |
  |   client_assertion (JWT)      |                              |
  |   grant_type                  |                              |
  |   scope                       |                              |
  |                               |                              |
  |        validate JWT sig       |                              |
  |        check jti replay       |                              |
  |        evaluate scopes        |                              |
  |                               |                              |
  |<-- access_token (Bearer) -----|                              |
  |    expires_in: 300            |                              |
  |                               |                              |
  |--- GET /fhir/Patient ---------|----------------------------->|
  |    Authorization: Bearer ...  |                              |
  |                               |       validate token        |
  |<-- 200 OK (Patient bundle) ---|------------------------------|

A Note on the Authorization Server Relationship

An important architectural decision that we have made: the Helios FHIR Server will not act as an authorization server. Client registration, token issuance, and the OAuth dance belong to a dedicated, independently scalable authorization server. HFS validates tokens. That is all.

This is a decision drawn from our experience building several large-scale systems.

First, operational reality. In production environments at scale, the authorization server and the FHIR resource server have fundamentally different operational characteristics. The authorization server handles short bursts of token requests; the FHIR server handles sustained, high-throughput data queries. They have different CPU and memory profiles, different scaling triggers, different failure modes, and different upgrade cadences. Conflating the two into a single process forces you to make the wrong trade-off for at least one of them.

Second, and more importantly: authorization servers are security-critical infrastructure. The mature open-source and commercial options - Keycloak, Okta, Auth0, Microsoft Entra ID, and others - represent years of battle-tested security engineering. Keycloak alone has over a decade of CVE patches, penetration testing, and hardening by the broader security community. Writing a correct OAuth authorization server requires getting JWT validation, key management, token revocation, replay prevention, timing-safe comparisons, and dozens of other subtle security details exactly right. Getting any one of them wrong can compromise an entire deployment. This is not a place to build from scratch when proven implementations exist.

What you will find in this design, accordingly, is not a custom authorization server. What you will find is a delegation model that integrates cleanly with the established identity providers that organizations already operate. The AuthProvider trait abstracts over the token validation contract - whether that means verifying a JWT signature against the authorization server's published JWKS, or calling a token introspection endpoint. Both paths produce a Principal that HFS can reason about. The source of truth for client registration, scope grants, and token issuance remains with the external authorization server throughout.

Decoupling also makes the authorization server independently replaceable. A self-hosted Keycloak today, a managed cloud identity provider tomorrow - none of these changes should require touching HFS. The integration point is a well-defined HTTP contract: HFS receives a token, validates it against the authorization server's published key material, and makes an access control decision based on the result.

This is consistent with every serious production deployment we have encountered.

---

Scopes: The Language of Authorization

SMART defines a scope syntax that maps directly onto FHIR operations and resource types. For backend services, all scopes are system/ scopes - there is no patient or user context. Some examples:

Scope	Meaning
system/*.rs	Read and search all resource types
system/Patient.rs	Read and search Patient resources
system/Observation.r	Read (but not search) Observation resources
system/Condition.crud	Full CRUD on Condition resources

The r = read, s = search, u = update, c = create, d = delete convention was introduced in SMART v2. The older v1 syntax (.read, .write, .) is also in use in the wild and must be understood.

Scopes form the bridge between authentication ("this is client X") and authorization ("client X may do Y"). After token validation, the scope string is the primary input to access control decisions.

---

The Two Faces of Key-Based Authentication

SMART Backend Services relies exclusively on asymmetric authentication - the client-confidential-asymmetric profile. There is no shared secret. The client holds a private key, registers the corresponding public key with the server, and proves identity by signing JWTs.

The supported algorithms are RS384 (RSA with SHA-384) and ES384 (ECDSA with P-384). Servers must support at least one; clients must support both.

Key verification works as follows: the server looks at the jku header in the client's JWT (an optional URL pointing to the client's JWKS endpoint) or falls back to the JWKS URL registered at enrollment time. It fetches the JWKS, finds the key matching the kid header, and verifies the signature. The server MUST NOT cache the JWKS longer than the client's Cache-Control header indicates - this is how key rotation works.

One subtlety worth noting: replay attack prevention. Every authentication JWT must carry a jti (JWT ID) claim. The server must track jti values and reject any that have been seen before within the token's allowed lifetime. Without this check, a stolen JWT could be used to impersonate the client.

---

Designing the Rust Traits

Following the same philosophy as the persistence layer - decompose the specification into cohesive concerns, express each as a focused trait, and compose them - here is how authentication and authorization can be modeled in Rust.

The Principal: Who Is Making This Request?

Before we can make access control decisions, we need to know who is asking. In the backend services context, every request comes from a registered client, not a human user. We model the authenticated identity as a Principal:

/// The authenticated identity behind a request.
/// For Backend Services, this is always a registered client.
/// Future: extend with User variant for SMART App Launch.
#[derive(Debug, Clone)]
pub enum Principal {
    /// A backend service client authenticated via client_credentials + JWT assertion.
    BackendService {
        /// The registered client_id
        client_id: String,
        /// The granted scopes for this access token
        scopes: ScopeSet,
        /// When this token expires
        expires_at: chrono::DateTime<chrono::Utc>,
        /// The issuer of the access token (authorization server URL)
        issuer: String,
    },
    /// A system-internal caller (e.g., administrative operations)
    System,
}

impl Principal {
    /// Returns the scopes granted to this principal, if any.
    pub fn scopes(&self) -> Option<&ScopeSet> {
        match self {
            Principal::BackendService { scopes, .. } => Some(scopes),
            Principal::System => None,
        }
    }

    /// Returns true if this token has expired.
    pub fn is_expired(&self) -> bool {
        match self {
            Principal::BackendService { expires_at, .. } => {
                *expires_at < chrono::Utc::now()
            }
            Principal::System => false,
        }
    }
}

Scopes as a First-Class Type

Rather than passing scope strings around and doing string matching everywhere, we model the SMART scope syntax as a structured type:

/// A parsed SMART scope for system-level access.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct SystemScope {
    /// The resource type, or None for wildcard (*)
    pub resource_type: Option<String>,
    /// The permitted operations
    pub permissions: ScopePermissions,
}

bitflags::bitflags! {
    /// Permissions encoded in a SMART scope.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub struct ScopePermissions: u8 {
        const READ   = 0b00001;
        const SEARCH = 0b00010;
        const CREATE = 0b00100;
        const UPDATE = 0b01000;
        const DELETE = 0b10000;

        // Common combinations
        const RS = Self::READ.bits() | Self::SEARCH.bits();
        const CRUD = Self::CREATE.bits() | Self::READ.bits()
                   | Self::UPDATE.bits() | Self::DELETE.bits();
    }
}

/// A set of scopes granted to a principal.
#[derive(Debug, Clone, Default)]
pub struct ScopeSet {
    system_scopes: Vec<SystemScope>,
}

impl ScopeSet {
    /// Parse a space-separated SMART scope string.
    pub fn parse(scope_str: &str) -> Result<Self, ScopeParseError> { ... }

    /// Returns true if this scope set permits the given operation
    /// on the given resource type.
    pub fn permits(
        &self,
        resource_type: &str,
        permission: ScopePermissions,
    ) -> bool {
        self.system_scopes.iter().any(|scope| {
            let type_matches = scope.resource_type.as_deref()
                .map(|t| t == resource_type)
                .unwrap_or(true); // wildcard
            type_matches && scope.permissions.contains(permission)
        })
    }
}

Token Validation: The AuthProvider Trait

Token validation is where authentication and authorization meet. A client presents a Bearer token; we need to turn that into a Principal. The AuthProvider trait abstracts over how this happens - whether we're validating a JWT locally against the authorization server's published JWKS, or calling a token introspection endpoint:

/// Errors that can occur during authentication and authorization.
#[derive(Debug, thiserror::Error)]
pub enum AuthError {
    #[error("missing or malformed Authorization header")]
    MissingCredentials,

    #[error("token has expired")]
    TokenExpired,

    #[error("invalid token signature")]
    InvalidSignature,

    #[error("token has been replayed (jti already seen)")]
    ReplayDetected,

    #[error("unknown client: {0}")]
    UnknownClient(String),

    #[error("token issuer not trusted: {0}")]
    UntrustedIssuer(String),

    #[error("insufficient scope: need {needed} on {resource_type}")]
    InsufficientScope {
        needed: String,
        resource_type: String,
    },

    #[error("internal auth error: {0}")]
    Internal(#[from] anyhow::Error),
}

/// Extracts and validates the principal from an incoming request.
///
/// Implementations may validate a JWT locally, call a token introspection
/// endpoint, or use any other mechanism. The interface is identical regardless.
#[async_trait::async_trait]
pub trait AuthProvider: Send + Sync {
    /// Authenticate a request from its Authorization header value.
    ///
    /// The `authorization` parameter is the raw value of the Authorization
    /// header (e.g., "Bearer eyJ..."). Returns the authenticated Principal
    /// or an error if authentication fails.
    async fn authenticate(&self, authorization: &str) -> Result<Principal, AuthError>;

    /// Returns a human-readable description of this auth provider,
    /// for use in logs and diagnostics.
    fn provider_name(&self) -> &'static str;
}

Two concrete implementations cover the two standard ways of validating tokens issued by an external authorization server:

/// Validates JWT Bearer tokens by verifying their signature against the
/// authorization server's published JWKS.
///
/// This is the preferred approach when the authorization server issues
/// self-contained signed JWTs (as most do). HFS fetches the authorization
/// server's public keys from its JWKS URI and verifies the signature locally
/// on every request, with key material cached according to Cache-Control headers.
///
/// The authorization server URL is configured at startup - HFS does not
/// accept tokens from unknown issuers.
pub struct JwksBearerAuthProvider {
    /// The JWKS URI of the authorization server
    /// (typically discovered via /.well-known/openid-configuration)
    jwks_uri: Url,
    /// Expected token issuer (must match the `iss` claim exactly)
    expected_issuer: String,
    /// Cached key material, refreshed per Cache-Control headers
    jwks_cache: Arc<RwLock<CachedJwks>>,
    /// HTTP client for fetching JWKS
    http_client: reqwest::Client,
    /// Replay attack prevention cache for client assertion JWTs
    jti_cache: Arc<JtiCache>,
}

/// Validates tokens by calling the authorization server's RFC 7662
/// Token Introspection endpoint.
///
/// Useful when the authorization server issues opaque (non-JWT) tokens,
/// or when you want the authorization server to make the active/inactive
/// determination authoritatively (e.g., to support immediate revocation).
/// Carries a network round-trip cost per request; mitigated by short-lived
/// response caching where the security posture permits it.
pub struct IntrospectionAuthProvider {
    /// The introspection endpoint URL
    introspection_endpoint: Url,
    /// Credentials for authenticating to the introspection endpoint
    /// (HFS itself must be a registered OAuth client to call introspection)
    client_credentials: ClientCredentials,
    /// HTTP client (with connection pooling and timeout configuration)
    http_client: reqwest::Client,
    /// Optional short-lived response cache.
    /// Cache duration should be much shorter than token lifetime
    /// to preserve revocation semantics.
    cache: Option<Arc<TokenCache>>,
}

Replay Attack Prevention

The jti (JWT ID) check is subtle but important. A client generates a one-time-use JWT to authenticate, and the server must ensure that JWT cannot be replayed. The cache must be scoped to (iss, jti) pairs, not just jti values, to prevent one client from polluting the namespace of another:

/// Tracks seen JWT IDs to prevent replay attacks.
///
/// JTI values are cached for the duration of the maximum allowed
/// JWT lifetime (typically a few minutes). Entries expire automatically.
pub struct JtiCache {
    inner: Arc<Mutex<LruCache<JtiKey, chrono::DateTime<chrono::Utc>>>>,
    max_jwt_lifetime: chrono::Duration,
}

/// A (issuer, jti) pair - the globally unique identity of a JWT.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct JtiKey {
    issuer: String,
    jti: String,
}

impl JtiCache {
    /// Records a JWT as seen. Returns an error if the (iss, jti) pair
    /// has been seen before within the allowed lifetime window.
    pub fn record(&self, issuer: &str, jti: &str, exp: chrono::DateTime<chrono::Utc>)
        -> Result<(), AuthError>
    {
        let key = JtiKey {
            issuer: issuer.to_string(),
            jti: jti.to_string(),
        };
        let mut cache = self.inner.lock().unwrap();
        if cache.contains(&key) {
            return Err(AuthError::ReplayDetected);
        }
        cache.put(key, exp);
        Ok(())
    }
}

No ClientRegistry in HFS

A natural question at this point: where does HFS store client registrations? The answer is that it doesn't. Client registrations - the client_id, the associated JWKS URL, the authorized scopes - all of that lives in the external authorization server. When an OAuth server registers a backend client, it manages that record. HFS has no opinion on it.

This is a deliberate boundary. If HFS maintained a parallel registry of clients, you would immediately have two sources of truth to keep in sync, two places where a revoked client might still appear active, and two administration surfaces to secure. The operational overhead compounds quickly, especially across the number of client applications a high-volume deployment typically accumulates.

What HFS does need to know is whether a given token is currently valid and what scopes it carries. The AuthProvider trait handles this - either by verifying the token's signature against the authorization server's published JWKS, or by calling the introspection endpoint. Both paths produce a Principal that HFS can reason about. The source of truth for the underlying authorization decision remains with the authorization server throughout.

Access Control: The AuthorizationPolicy Trait

Authentication establishes who is making a request. Authorization answers what they're allowed to do. While scope-based checks cover the SMART specification requirements, real deployments often need additional policy - row-level security, compartment-based restrictions, tenant isolation enforcement. We separate this concern into its own trait:

/// Describes a FHIR operation for authorization purposes.
#[derive(Debug, Clone)]
pub struct FhirOperation {
    /// The resource type being operated on (e.g., "Patient")
    pub resource_type: String,
    /// The specific interaction
    pub interaction: Interaction,
    /// The resource ID (for instance-level operations)
    pub resource_id: Option<String>,
    /// The tenant context
    pub tenant: TenantContext,
}

/// The outcome of an authorization check.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthDecision {
    /// The operation is permitted.
    Permit,
    /// The operation is denied.
    Deny {
        /// A reason code suitable for logging (not for returning to clients)
        reason: DenyReason,
    },
    /// The operation is permitted but results should be filtered.
    /// Used for partial access - e.g., a client can see Observations
    /// but only those matching a certain criteria.
    PermitWithFilter(ResourceFilter),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DenyReason {
    InsufficientScope,
    CrossTenantAccess,
    ClientRevoked,
    PolicyViolation(String),
}

/// Evaluates whether a principal may perform a FHIR operation.
///
/// This is intentionally separate from token validation. Token validation
/// answers "is this token genuine?". Policy evaluation answers "is this
/// token allowed to do this thing right now?". Separating the two makes
/// each independently testable and replaceable.
#[async_trait::async_trait]
pub trait AuthorizationPolicy: Send + Sync {
    /// Evaluate whether the principal may perform the operation.
    async fn evaluate(
        &self,
        principal: &Principal,
        operation: &FhirOperation,
    ) -> Result<AuthDecision, AuthError>;

    /// Returns the policy name, for logging and audit trails.
    fn policy_name(&self) -> &'static str;
}

A scope-based policy is the default and covers all SMART-compliant behavior:

/// Authorization policy that enforces SMART scope rules.
///
/// This is the baseline policy. Most deployments will use this alone
/// or compose it with additional policies via CompositeAuthorizationPolicy.
pub struct SmartScopePolicy;

#[async_trait::async_trait]
impl AuthorizationPolicy for SmartScopePolicy {
    async fn evaluate(
        &self,
        principal: &Principal,
        operation: &FhirOperation,
    ) -> Result<AuthDecision, AuthError> {
        let Some(scopes) = principal.scopes() else {
            // System principal has no scopes but is always permitted
            return Ok(AuthDecision::Permit);
        };

        let required = match operation.interaction {
            Interaction::Read | Interaction::Vread => ScopePermissions::READ,
            Interaction::Search => ScopePermissions::SEARCH,
            Interaction::Create => ScopePermissions::CREATE,
            Interaction::Update => ScopePermissions::UPDATE,
            Interaction::Delete => ScopePermissions::DELETE,
            Interaction::History => ScopePermissions::READ,
            // etc.
        };

        if scopes.permits(&operation.resource_type, required) {
            Ok(AuthDecision::Permit)
        } else {
            Ok(AuthDecision::Deny {
                reason: DenyReason::InsufficientScope,
            })
        }
    }

    fn policy_name(&self) -> &'static str { "SmartScopePolicy" }
}

Policies can be composed without coupling them together:

/// Evaluates multiple policies in order, taking the most restrictive result.
///
/// If any policy Denies, the overall decision is Deny.
/// If all policies Permit, the overall decision is Permit.
/// PermitWithFilter results are merged.
pub struct CompositeAuthorizationPolicy {
    policies: Vec<Box<dyn AuthorizationPolicy>>,
}

The Discovery Endpoint

The /.well-known/smart-configuration document is how clients learn about the server's capabilities. We model its content as a typed struct that can serialize to JSON:

/// The SMART configuration discovery document.
/// Served at `/.well-known/smart-configuration` relative to the FHIR base URL.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct SmartConfiguration {
    /// REQUIRED: URL to the OAuth2 token endpoint.
    pub token_endpoint: Url,

    /// REQUIRED: Grant types supported at the token endpoint.
    /// For Backend Services, this must include "client_credentials".
    pub grant_types_supported: Vec<String>,

    /// REQUIRED: Array of SMART capability strings.
    pub capabilities: Vec<String>,

    /// REQUIRED: PKCE code challenge methods supported.
    /// S256 must be present; plain must not be.
    pub code_challenge_methods_supported: Vec<String>,

    /// RECOMMENDED: URL to the token introspection endpoint.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub introspection_endpoint: Option<Url>,

    /// RECOMMENDED: URL to the token revocation endpoint.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub revocation_endpoint: Option<Url>,

    /// OPTIONAL: Supported client authentication methods.
    /// For Backend Services, should include "private_key_jwt".
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token_endpoint_auth_methods_supported: Option<Vec<String>>,

    /// OPTIONAL: Supported signing algorithms for client assertions.
    /// Should include at least one of RS384, ES384.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token_endpoint_auth_signing_alg_values_supported: Option<Vec<String>>,
}

impl SmartConfiguration {
    /// Returns a minimal configuration suitable for Backend Services only.
    pub fn backend_services_only(token_endpoint: Url) -> Self {
        Self {
            token_endpoint,
            grant_types_supported: vec!["client_credentials".into()],
            capabilities: vec!["client-confidential-asymmetric".into()],
            code_challenge_methods_supported: vec!["S256".into()],
            token_endpoint_auth_methods_supported: Some(vec!["private_key_jwt".into()]),
            token_endpoint_auth_signing_alg_values_supported: Some(
                vec!["RS384".into(), "ES384".into()]
            ),
            ..Default::default()
        }
    }
}

Putting It Together: The Auth Layer as a Middleware

The auth layer sits between the network and the FHIR request handlers. Every incoming request passes through it. The RequestContext produced here is the single source of truth for the rest of the system about who is making this request:

/// The authenticated and authorized context for a single FHIR request.
/// Produced by the auth layer, consumed by resource handlers and storage.
#[derive(Debug, Clone)]
pub struct RequestContext {
    /// The authenticated principal
    pub principal: Principal,
    /// The tenant scope of this request
    pub tenant: TenantContext,
    /// A unique ID for this request (for correlation in audit logs)
    pub request_id: uuid::Uuid,
    /// The time this request was authenticated
    pub authenticated_at: chrono::DateTime<chrono::Utc>,
}

/// The authentication and authorization middleware.
pub struct AuthMiddleware {
    provider: Arc<dyn AuthProvider>,
    policy: Arc<dyn AuthorizationPolicy>,
    tenant_resolver: Arc<dyn TenantResolver>,
}

impl AuthMiddleware {
    /// Authenticate an incoming request and produce a RequestContext.
    ///
    /// This is called once per request, before any FHIR processing.
    pub async fn authenticate_request(
        &self,
        authorization_header: Option<&str>,
        tenant_hint: Option<&str>,
    ) -> Result<RequestContext, AuthError> {
        let authorization = authorization_header
            .ok_or(AuthError::MissingCredentials)?;

        let principal = self.provider.authenticate(authorization).await?;

        if principal.is_expired() {
            return Err(AuthError::TokenExpired);
        }

        let tenant = self.tenant_resolver.resolve(tenant_hint, &principal).await?;

        Ok(RequestContext {
            principal,
            tenant,
            request_id: uuid::Uuid::new_v4(),
            authenticated_at: chrono::Utc::now(),
        })
    }

    /// Check whether a principal may perform a specific operation.
    ///
    /// Called by resource handlers before executing FHIR operations.
    pub async fn authorize(
        &self,
        ctx: &RequestContext,
        operation: &FhirOperation,
    ) -> Result<AuthDecision, AuthError> {
        self.policy.evaluate(&ctx.principal, operation).await
    }
}

---

Identity Provider Integration: How Real-World Services Plug In

The architectural decision to keep HFS out of the authorization server business is not merely a theoretical preference - it is what makes the system work with the identity providers that organizations already have deployed. Every major cloud identity platform and open-source authorization server speaks OAuth 2.0 and publishes JWKS endpoints. The AuthProvider trait is deliberately shaped to exploit this convergence.

Here is how the most commonly encountered providers map onto the design.

Keycloak

Keycloak is the open-source option that many healthcare organizations gravitate toward because it can be self-hosted - an important consideration when data sovereignty requirements preclude cloud-hosted identity. It is also the most natural fit for SMART-on-FHIR because of its extensibility.

How it connects:

Keycloak exposes a JWKS endpoint at {keycloak-url}/realms/{realm}/protocol/openid-connect/certs. The JwksBearerAuthProvider points at this URL and validates tokens locally. Keycloak's token endpoint ({keycloak-url}/realms/{realm}/protocol/openid-connect/token) is the URL that appears in the /.well-known/smart-configuration document served by HFS.

Scopes and client credentials:

Keycloak supports the client_credentials grant type natively. Backend service clients are registered as "confidential" clients with a service account enabled. SMART v2 scopes (system/Patient.rs, etc.) are configured as client scopes in Keycloak - either as default scopes assigned at registration or as optional scopes that the client requests at token time.

SMART-specific considerations:

Out of the box, Keycloak does not understand SMART scope syntax - it treats scopes as opaque strings. This is fine for HFS, which parses the scope string from the token itself via ScopeSet::parse(). However, if you want Keycloak to enforce scope restrictions at the authorization server level (rejecting requests for scopes a client isn't authorized to hold), you need to configure Keycloak's client scope mappings to match the SMART scope vocabulary. Community extensions exist that add SMART-aware scope validation to Keycloak directly.

Configuration sketch:

# HFS environment
HFS_AUTH_JWKS_URI=https://keycloak.example.org/realms/fhir/protocol/openid-connect/certs
HFS_AUTH_EXPECTED_ISSUER=https://keycloak.example.org/realms/fhir
HFS_AUTH_TOKEN_ENDPOINT=https://keycloak.example.org/realms/fhir/protocol/openid-connect/token

Okta

Okta is widely deployed in US healthcare, particularly among larger health systems and payer organizations. Its appeal is operational simplicity - it is a fully managed service with strong compliance certifications (SOC 2, HIPAA BAA available).

How it connects:

Okta publishes JWKS at https://{okta-domain}/oauth2/{authorization-server-id}/v1/keys. For the default authorization server, the path is https://{okta-domain}/oauth2/default/v1/keys. The JwksBearerAuthProvider fetches keys from this endpoint.

Scopes and client credentials:

Backend services in Okta are configured as "Service" application types using the client_credentials grant. Custom scopes are defined on the Okta authorization server - you create scopes matching the SMART syntax (system/Patient.rs, system/Observation.r, etc.) and assign them to the service application via an access policy.

Token format:

Okta issues JWTs by default, which is ideal for the JwksBearerAuthProvider path. The tokens include standard claims (iss, sub, aud, exp, iat) plus a scp claim containing the granted scopes as an array of strings. Note that Okta uses scp (an array) rather than the OAuth standard scope (a space-delimited string) - the ScopeSet::parse() implementation should handle both formats.

Configuration sketch:

HFS_AUTH_JWKS_URI=https://dev-123456.okta.com/oauth2/default/v1/keys
HFS_AUTH_EXPECTED_ISSUER=https://dev-123456.okta.com/oauth2/default
HFS_AUTH_TOKEN_ENDPOINT=https://dev-123456.okta.com/oauth2/default/v1/token

Auth0

Auth0 (now part of Okta, Inc., but operated as a separate platform) is popular among digital health startups and smaller organizations building FHIR integrations. Its developer experience is polished, and it supports the client_credentials grant out of the box.

How it connects:

Auth0's JWKS endpoint is at https://{tenant}.auth0.com/.well-known/jwks.json (or https://{custom-domain}/.well-known/jwks.json for custom domains). The JwksBearerAuthProvider works without modification.

Scopes and client credentials:

Machine-to-machine applications in Auth0 are authorized against an "API" (Auth0's term for a resource server). You define the API with an identifier (typically the FHIR server's base URL), create custom scopes matching SMART syntax, and authorize specific M2M applications to request those scopes.

Token format:

Auth0 issues RS256-signed JWTs by default. The scope claim is a space-delimited string (standard OAuth format). The aud (audience) claim contains the API identifier - HFS should validate this matches its own base URL to prevent token confusion attacks where a token issued for a different API is presented to HFS.

Audience validation note:

This is worth calling out because it affects the AuthProvider trait. Auth0 tokens carry an aud claim, and Auth0's documentation strongly recommends validating it. The JwksBearerAuthProvider should accept an expected_audience configuration alongside expected_issuer. This is good practice regardless of provider - it prevents a token issued by the same authorization server but intended for a different resource server from being accepted by HFS.

Configuration sketch:

HFS_AUTH_JWKS_URI=https://your-tenant.auth0.com/.well-known/jwks.json
HFS_AUTH_EXPECTED_ISSUER=https://your-tenant.auth0.com/
HFS_AUTH_TOKEN_ENDPOINT=https://your-tenant.auth0.com/oauth/token
HFS_AUTH_EXPECTED_AUDIENCE=https://fhir.example.org

Microsoft Entra ID (Azure AD)

Microsoft Entra ID (formerly Azure Active Directory) is the dominant identity platform in enterprises using Azure. Many hospital systems running on Azure already have Entra ID deployed for workforce identity, making it a natural choice for FHIR API authorization as well. Microsoft also offers the Azure Health Data Services FHIR service, so organizations integrating HFS alongside Azure FHIR will often share the same Entra ID tenant.

How it connects:

Entra ID publishes JWKS at https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys. The JwksBearerAuthProvider points here. Note the tenant-specific URL - Entra ID is a multi-tenant platform, and you must configure HFS with your specific tenant's JWKS endpoint to avoid accepting tokens from other tenants.

Scopes and client credentials:

Backend services are registered as "App registrations" in Entra ID. The client_credentials flow is supported natively. Scopes in Entra ID are defined as "Application permissions" (also called "app roles") on the target application registration. You define permissions matching SMART scope strings and grant them to the calling application via admin consent.

Token format:

Entra ID v2.0 tokens are JWTs signed with RS256. The key claims are:

• iss: https://login.microsoftonline.com/{tenant-id}/v2.0
• aud: the Application ID URI of the target app registration
• roles: an array of granted application permissions (this is where SMART scopes appear)

Important distinction: Entra ID places application permissions in a roles claim, not a scope or scp claim. The scope claim in a client_credentials token from Entra ID typically contains only a default scope (e.g., https://fhir.example.org/.default). The actual fine-grained permissions are in roles. The ScopeSet parser needs to be aware of this provider-specific mapping - or, more cleanly, the JwksBearerAuthProvider should be configurable with the claim name from which to extract scopes.

Configuration sketch:

HFS_AUTH_JWKS_URI=https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys
HFS_AUTH_EXPECTED_ISSUER=https://login.microsoftonline.com/{tenant-id}/v2.0
HFS_AUTH_TOKEN_ENDPOINT=https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
HFS_AUTH_EXPECTED_AUDIENCE=api://hfs-fhir-server
HFS_AUTH_SCOPE_CLAIM=roles

Google Cloud Identity (GCP)

Google Cloud's identity platform is relevant for organizations running healthcare workloads on GCP, and it integrates with Google's Healthcare API. GCP's approach to service-to-service authentication uses Google-signed JWTs and service accounts.

How it connects:

Google's JWKS endpoint is at https://www.googleapis.com/oauth2/v3/certs. Service accounts authenticate via the client_credentials-equivalent flow: the service account creates a self-signed JWT, exchanges it at https://oauth2.googleapis.com/token, and receives a Google-signed access token. The JwksBearerAuthProvider validates tokens against Google's published keys.

Scopes and service accounts:

GCP uses service accounts for machine-to-machine authentication. Scopes in GCP are typically Google API scopes (https://www.googleapis.com/auth/...), not SMART scopes. To map this to the SMART model, there are two approaches:

1. Custom scopes via Workforce Identity Federation or API Gateway: Use Google's API Gateway or Identity-Aware Proxy to attach custom SMART scopes to tokens before they reach HFS. The gateway acts as a token exchange layer.
2. Service account metadata mapping: Register each GCP service account's email as a client_id equivalent in an external scope mapping configuration. HFS (or a lightweight proxy) maps the authenticated service account identity to SMART scopes via a lookup.

Token format:

Google-issued access tokens are opaque by default (not JWTs). However, Google-signed identity tokens (obtained by specifying a target audience) are JWTs and can be validated against Google's JWKS. For HFS integration, you want identity tokens, not access tokens.

Practical consideration:

GCP's identity model is the least natural fit for SMART Backend Services among the providers discussed here, because Google's scope system is Google-API-centric rather than application-defined. Organizations on GCP may find it cleaner to deploy Keycloak on GKE as their SMART authorization server and use GCP's identity platform for authenticating to Keycloak itself, rather than trying to make Google's token format directly express SMART scopes.

What This Means for the Trait Design

The provider survey above surfaces a few concrete requirements for the JwksBearerAuthProvider:

1. Configurable scope claim name: Okta uses scp (array), Auth0 uses scope (string), Entra ID uses roles (array), and the OAuth standard says scope (string). The provider must know which claim to read.

2. Audience validation: Auth0 and Entra ID both require aud claim validation. This should be a standard, not optional, part of token validation - even Keycloak and Okta benefit from it as a defense-in-depth measure.

3. Multiple scope formats: Space-delimited strings and JSON arrays are both in use. ScopeSet::parse() should handle both transparently.

4. Issuer URL strictness: Trailing slashes matter. Auth0 issues tokens with iss: "https://tenant.auth0.com/" (trailing slash), while Entra ID does not. Issuer comparison must be exact, but the configuration documentation should call this out.

These are not esoteric edge cases - they are the first things you encounter when connecting a real identity provider. By making them explicit in the trait design, we avoid the situation where the JwksBearerAuthProvider works perfectly against a test JWKS endpoint but fails on the first real deployment.

Here is the JwksBearerAuthProvider struct updated to reflect these requirements:

pub struct JwksBearerAuthProvider {
    /// The JWKS URI of the authorization server
    jwks_uri: Url,
    /// Expected token issuer (must match the `iss` claim exactly, including trailing slash)
    expected_issuer: String,
    /// Expected audience (must match the `aud` claim). Recommended for all providers.
    expected_audience: Option<String>,
    /// The JWT claim name containing granted scopes.
    /// Defaults to "scope". Set to "scp" for Okta, "roles" for Entra ID.
    scope_claim: String,
    /// Cached key material, refreshed per Cache-Control headers
    jwks_cache: Arc<RwLock<CachedJwks>>,
    /// HTTP client for fetching JWKS
    http_client: reqwest::Client,
    /// Replay attack prevention cache
    jti_cache: Arc<JtiCache>,
}

---

AI Agents as Backend Service Clients

The same AI-driven forces mentioned in the introduction - clinical decision support engines, analytics pipelines, population health platforms - increasingly take the form of autonomous AI agents. These agents need programmatic access to FHIR APIs just like any other backend service. The good news is that the SMART Backend Services protocol and the client-confidential-asymmetric authentication profile are already designed for exactly this kind of machine-to-machine interaction. No new protocol is needed. What is needed is a clear picture of how an AI agent registers, authenticates, and operates within the existing framework.

The Registration Flow for an AI Agent

AI agent registration follows the standard SMART client-confidential-asymmetric registration protocol. The process happens at the authorization server - not at HFS - and the key steps are:

1. Key pair generation

The AI agent (or the system that provisions it) generates an asymmetric key pair. SMART requires support for both RS384 (RSA with SHA-384) and ES384 (ECDSA with P-384). The private key stays with the agent; the public key is communicated to the authorization server.

2. Public key registration

The agent's public key is registered with the authorization server as a JSON Web Key (JWK) within a JWK Set, per RFC 7517. There are two methods:

• JWKS URL (preferred): The agent hosts its public keys at a TLS-protected URL accessible without authentication. The authorization server fetches keys from this URL on demand. This is the preferred method because it enables key rotation without re-registering - the agent publishes a new key at the same URL, and the authorization server picks it up on its next fetch (respecting Cache-Control headers). For AI agents running in cloud environments, this URL is typically a well-known endpoint on the agent's own infrastructure.

• JWK Set directly (supported but discouraged): The agent provides its JWK Set at registration time. The authorization server stores the key material. This prevents in-band key rotation - if the agent needs to rotate keys, it must re-register. The spec recommends including a successor key alongside the active key to mitigate this limitation.

Each JWK must include a kid (Key ID) that is unique within the agent's key set. For RSA keys, the required fields are kty, kid, n, and e. For ECDSA keys: kty, kid, crv, x, and y.

3. Scope assignment

The administrator configures which SMART scopes the agent is authorized to request. For example, a clinical decision support agent might receive system/Patient.rs system/Observation.rs system/Condition.rs - read and search access to the clinical data it needs for its reasoning, but no write access. A data integration agent synchronizing patient demographics might receive system/Patient.crud. The principle of least privilege applies: agents should receive only the scopes their function requires.

4. Client ID issuance

The authorization server assigns the agent a client_id. This is the identity that the agent will assert in its authentication JWTs.

How the Agent Authenticates

Once registered, the agent authenticates using the standard client_credentials flow with a signed JWT assertion. The sequence is identical to any other backend service client:

1. The agent constructs a JWT with the following claims:

   • iss: the agent's client_id
   • sub: the agent's client_id
   • aud: the authorization server's token endpoint URL
   • exp: expiration time (maximum 5 minutes in the future)
   • jti: a unique identifier for this JWT (for replay prevention)

2. The JWT header includes:

   • alg: RS384 or ES384
   • kid: the Key ID matching the registered public key
   • typ: JWT
   • jku (optional): the URL of the agent's JWKS endpoint, if one was registered

3. The agent signs the JWT with its private key and POSTs to the token endpoint:

   POST /token HTTP/1.1
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=client_credentials
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion=eyJ...signed-jwt...
   &scope=system/Patient.rs system/Observation.rs
   

4. The authorization server validates the JWT:

   • Verifies the jku header (if present) matches the registration-time JWKS URL
   • Fetches the public key (from jku or the registered JWKS URL) and matches by kid
   • Verifies the JWT signature
   • Checks that jti has not been seen before within the allowed lifetime window
   • Confirms the client_id is known and matches the JWT iss claim
   • Evaluates the requested scopes against the client's authorized scopes

5. If validation succeeds, the authorization server issues a short-lived access token (recommended maximum lifetime: 5 minutes).

6. The agent presents this token as a Bearer token on every FHIR API request to HFS. HFS validates the token via its AuthProvider (JWKS signature verification or token introspection) and enforces scope-based access control via its AuthorizationPolicy.

Provider-Specific Registration for AI Agents

Each identity provider has its own administrative interface for registering backend service clients. Here is how AI agent registration maps to the providers discussed earlier:

Provider	Registration method	Key configuration
Keycloak	Create a "confidential" client with "Service accounts roles" enabled. Upload the agent's JWKS URL or public key under the client's "Keys" tab. Assign SMART scopes as client scopes.	Realm → Clients → Create → Service Account Enabled
Okta	Create a "Service" application type. Configure the client_credentials grant. Add custom SMART scopes to the authorization server and assign them via an access policy. Upload the agent's public key (JWKS).	Applications → Create App → Service
Auth0	Create a "Machine to Machine" application. Authorize it against an API (resource server) that defines SMART scopes. Provide the agent's public key or JWKS URL as credentials.	Applications → Create → M2M → Authorize API
Entra ID	Create an "App registration". Define SMART scopes as application permissions (app roles). Grant admin consent for the agent application. Configure certificate-based credentials with the agent's public key.	App registrations → New → API permissions → Application
Keycloak (Docker Compose)	For development and testing, a pre-configured Keycloak realm with SMART scopes and sample agent registrations can be provided as part of the HFS development environment.	docker compose up with bundled realm export

Key Rotation for Long-Running Agents

AI agents that run continuously (monitoring services, real-time alerting, continuous data pipelines) will eventually need to rotate their cryptographic keys. The JWKS URL method makes this straightforward:

1. The agent generates a new key pair and adds the new public key to its published JWKS, alongside the existing key (each with a distinct kid).
2. The agent begins signing new JWTs with the new key.
3. After a grace period (long enough for all cached copies of the old JWKS to expire, governed by Cache-Control headers), the agent removes the old public key from its JWKS.

The authorization server and HFS require no reconfiguration. The key rotation is entirely self-service, which is important for environments with many AI agents that may be provisioned and managed programmatically.

Scope Governance for AI Agents

The composable AuthorizationPolicy trait is particularly relevant for AI agent deployments. Beyond basic SMART scope enforcement, organizations may want to layer additional policies:

• Rate limiting per agent: An AI agent with system/Patient.rs could read every patient in the system. A rate-limiting policy can throttle request volume.
• Compartment restrictions: An agent authorized for system/Observation.rs might be restricted to observations linked to patients within a specific care team or facility.
• Temporal access windows: An analytics agent might only be authorized to run during off-peak hours.
• Audit-intensive policies: AI agents accessing clinical data may warrant enhanced audit logging - recording not just the access decision but the volume of data returned.

These are implemented as AuthorizationPolicy trait objects composed via CompositeAuthorizationPolicy, exactly as described in the trait design section. The agent itself is unaware of these policies - it authenticates, receives a token, and makes FHIR requests. The policy enforcement is entirely server-side.

---

The FHIR security specification gives careful guidance on how to respond when access is denied - and the guidance is deliberately conservative. Returning too much information about why access was denied can leak data:

• Return a success with an empty Bundle: indistinguishable from "no data found". Use this when you don't want to reveal whether a resource exists at all.
• Return 404 Not Found: also hides whether a resource exists, but reveals that authentication succeeded.
• Return 403 Forbidden: communicates that authorization failed, but only use this when the client can reasonably be expected to understand the rejection.
• Return 401 Unauthorized: signals that authentication itself failed.

The Helios FHIR Server will make these decisions via policy configuration - defaulting to 404 for most access denials, with the exact behavior configurable per deployment.

---

Audit Logging: Non-Negotiable

Every access control decision must be recorded. This is both a FHIR recommendation and a regulatory requirement in most jurisdictions (HIPAA's accounting of disclosures, for instance). Audit events record who accessed what, when, from where, and whether access was granted or denied.

The auth layer is responsible for emitting these events, and they flow to the AuditStorage trait described in the persistence layer discussion:

/// An audit event emitted by the auth layer.
///
/// These are recorded regardless of whether access was granted or denied.
/// Denied operations MUST be recorded; permitted operations SHOULD be.
#[derive(Debug, Clone)]
pub struct AuthAuditEvent {
    pub request_id: uuid::Uuid,
    pub principal: Principal,
    pub operation: FhirOperation,
    pub decision: AuthDecision,
    pub timestamp: chrono::DateTime<chrono::Utc>,
    /// IP address of the client, if available
    pub client_ip: Option<std::net::IpAddr>,
}

---

What's Not in Scope (Yet)

This document focuses on Backend Services. Several related concerns are deferred:

• SMART App Launch (user-facing OAuth flow): This requires a UI and a user session model. When we build a UI for HFS, the Principal enum gains a User variant and the AuthProvider trait gains OAuth PKCE code exchange support.
• Consent enforcement: FHIR's Consent resource and the patient-directed access control it enables are a rich topic on their own.
• Dynamic Client Registration: RFC 7591 describes a programmatic registration protocol. Client registration is handled by the external authorization server; HFS does not implement a registration endpoint. Providers like Keycloak and Auth0 support dynamic registration natively for organizations that need it.
• UDAP (Unified Data Access Profiles): For scalable B2B trust federation, UDAP adds discovery and tiered trust on top of SMART. The FHIR security specification recommends it for scalable deployments.

---

Proposed Next Steps

The traits sketched above are a starting point. To move toward implementation:

1. Implement both token validation strategies: JwksBearerAuthProvider (signature verification against the authorization server's JWKS) and IntrospectionAuthProvider (round-trip to the introspection endpoint), and let operators choose. JWKS-based validation is the recommended default for high-throughput deployments since it avoids a network call on every request. Introspection is the fallback for authorization servers that issue opaque tokens or where immediate revocation semantics are required.
2. Settle the JWKS caching strategy: The spec says we must honor Cache-Control headers from JWKS endpoints. We need an HTTP client with correct cache semantics here, and a cache-busting path for key rotation events.
3. Define the tenant ↔ authorization relationship: How do client_id and TenantContext map to each other? One client per tenant? Multiple clients per tenant? This affects the TenantResolver design.
4. Choose a jti cache backend: An in-memory LRU cache is sufficient for single-instance deployments. Distributed deployments need a shared cache (Redis is the obvious choice) so that a replayed client-assertion JWT cannot slip through on a different HFS instance.
5. Build the Keycloak development environment: Provide a Docker Compose configuration with a pre-configured Keycloak realm that includes SMART scopes, sample backend service client registrations (including an example AI agent), and a ready-to-use token endpoint. This gives developers a zero-configuration path to running HFS with authentication enabled.
6. Write conformance tests: The SMART specification has a published test suite. Conformance testing should be automated against the bundled Keycloak instance, and integration tested against at least one cloud provider (Okta or Auth0) to verify the provider-specific claim mappings (scp, scope, roles) described in the identity provider section.

---

Closing Thoughts

Authentication and authorization in healthcare interoperability are load-bearing infrastructure. They protect patient data, enable regulatory compliance, and establish the trust relationships that make clinical AI workloads possible. Getting the design right matters - and getting it testable and composable matters almost as much.

The Rust trait system is a natural fit for this problem. The compiler enforces that every code path produces a RequestContext, that no storage operation happens without a TenantContext, and that new auth providers or policy implementations must satisfy the same contracts as the ones they replace. These guarantees hold regardless of how complex the deployment becomes.

Thank you for reading. I look forward to the discussion.

• Steve

[aacruzgon]

Hello Steve, I want to make sure I fully understand the architectural boundary being proposed.

From the discussion, my current understanding is:

• HFS does not act as an OAuth Authorization Server.
• Client registration, credential validation, token issuance, and the OAuth flows are delegated to an external Authorization Server.
• HFS receives a Bearer token and performs local JWT validation (signature verification, issuer/audience checks, expiry validation).
• No per-request introspection call is required in the default model.
• After token validation, HFS extracts scopes and enforces authorization policy internally (resource type, read/write, tenant boundaries, etc.).

So in other words:

• Authentication (identity proof) is delegated externally.
• Token validation is performed locally.
• Authorization policy enforcement remains inside HFS.

Is that the intended separation of responsibilities?

Additionally, when the discussion says “HFS validates tokens. That is all.” — I interpret that to mean HFS does not perform OAuth flows or issue tokens, but it still owns application-level authorization enforcement. Is that correct?

[smunini]

Hi @aacruzgon ,

HFS does not act as an OAuth Authorization Server.

Correct. I have found that in large (and even smaller) enterprises, because that part of the architecture is so critical from a security perspective that they will want to be running a known solution, and in many cases that already have one installed that they prefer to use. Additionally, there are certain scaling factors that are best handled by a different solution. In reality, these security servers are specialize and highly protected and managed in healthcare organizations.

Client registration, credential validation, token issuance, and the OAuth flows are delegated to an external Authorization Server.

Correct - for the same reasons as above.

HFS receives a Bearer token and performs local JWT validation (signature verification, issuer/audience checks, expiry validation).

Correct - The default path in JwksBearerAuthProvider fetches the Authorization Server's published JWKS, caches the key material per Cache-Control headers, and verifies the token signature locally - no per-request network call.

No per-request introspection call is required in the default model.

Yep!

After token validation, HFS extracts scopes and enforces authorization policy internally (resource type, read/write, tenant boundaries, etc.).

Correct. After a Principal is established from a validated token, the AuthorizationPolicy trait takes over - scope checks, tenant boundary enforcement, compartment restrictions, whatever the deployment requires. That logic lives in HFS, not in the Authorization Server.

So in other words:

• Authentication (identity proof) is delegated externally.
• Token validation is performed locally.
• Authorization policy enforcement remains inside HFS.
• Is that the intended separation of responsibilities?

You got it!

Your reading of "HFS validates tokens. That is all." is also correct. That sentence is deliberately scoped: HFS doesn't issue tokens, doesn't run OAuth flows, doesn't register clients. But it absolutely owns the application-level access control decision once a token has been validated. The AuthProvider/AuthorizationPolicy separation in the trait design is precisely what makes that boundary explicit and independently testable.

One small nuance worth adding: the JwksBearerAuthProvider does need to verify more than just the signature — issuer (iss), audience (aud), expiry (exp), and jti replay prevention are all part of "local JWT validation" in the design. The audience check in particular is worth calling out because it prevents a token issued by the same Authorization Server for a different resource server from being accepted by HFS (a token confusion attack). The updated JwksBearerAuthProvider struct in the provider survey section reflects expected_audience as a first-class field for exactly this reason.

[sandhums]

@smunini , As you did in the Persistence Layer, this is a very well put together document for authorization and authentication. I particularly admire the scopes design and separation of token validation and AuthorizationPolicy.

I have done some work on this earlier, and I had gone the implementing an own OAuth server route. (I did read your decisions regarding using open source and commercial authorization servers). I implemented an OAuth 2.1 with PKCE / OIDC-oriented IdP with multi-tenant semantics (organization → hospital) baked into the model, including OAuth client registration/management and user registration tied to client_id (hospital/client context). Redis cache’s for replay protection and session management.

What I visualized was that each organization/hospital would have multiple clients. You can have patient-facing apps, a website/SPA, desktop applications for billing staff, service to service API’s (what you are proposing to implement first), etc
All frontend clients have Passkey and MFA support (OTP/TOTP)

The authentication flows which are needed -

1. Web application/ SPA client – Has a separate BFF (Backend for frontend) server so that Access and refresh tokens are stored securely on the server-side within the BFF.
2. First Party Mobile App/Desktop Clients – uses the Authorization Challenge Endpoint with Sender constrained tokens with DpOP (demonstrating proof of possesion) and additionally device binding.
3. Service to Service API – uses Client credentials grant for confidential clients (RFC 6749) with additional mTLS support (RFC 8705)
4. SMART-on-FHIR - Essentially client-credentials with signed JWT assertions (system-to-system FHIR access).
   Proposed flows

• Device Authorization Grant (“device code”)

  For kiosks, TVs in waiting rooms, imaging consoles, ward tablets without full browser.

• CIBA (Backchannel auth)

  For decoupled approvals (e.g., clinician approves on phone while action originates elsewhere).

Some discussion points

• Delegating token issuance to Keycloak/Okta/Entra makes a lot of sense, but many healthcare deployments still want an in-house authorization control plane for org/hospital membership, role assignment, department/group constraints, and audit governance — even if authentication is federated. Otherwise the operational pressure is to encode hospital semantics into IdP roles/groups, which tends to get brittle. Maybe Your AuthorizationPolicy + TenantResolver looks like exactly the right place to plug that in.

• TenantResolver - In practice, isn’t it risky, letting the client provide a tenant_hint unless tenant context is either (a) derived deterministically from trusted token claims or (b) selected via a token exchange step that mints a tenant-bound token (audience + tenant claim), so the tenant context is cryptographically bound and can’t be “switched” by request metadata.

• Client registry “not in HFS” is fine — but healthcare still needs a registry somewhere, Not necessarily in HFS, but you still need a source of truth for:

  • which clients map to which org/hospital(s)
  • what compartment filters apply
  • which AI agents are allowed to read which facilities

[smunini]

Hi @sandhums,

@smunini , As you did in the Persistence Layer, this is a very well put together document for authorization and authentication. I particularly admire the scopes design and separation of token validation and AuthorizationPolicy.

Thanks!

I have done some work on this earlier, and I had gone the implementing an own OAuth server route. (I did read your decisions regarding using open source and commercial authorization servers). I implemented an OAuth 2.1 with PKCE / OIDC-oriented IdP with multi-tenant semantics (organization → hospital) baked into the model, including OAuth client registration/management and user registration tied to client_id (hospital/client context). Redis cache’s for replay protection and session management.

What I visualized was that each organization/hospital would have multiple clients. You can have patient-facing apps, a website/SPA, desktop applications for billing staff, service to service API’s (what you are proposing to implement first), etc
All frontend clients have Passkey and MFA support (OTP/TOTP)

I have implemented something similar for several clients - including the Redis cache (well, the AWS version of Redis), and there are some good libraries for supporting these standards, however I found there are always updates and various security vulnerabilities to keep on top of. Happily there are some good vendors in this space that provide mature services that focus only on this part of the architecture. It's a put all of your eggs in one basket and keep a close eye on the basket approach.

The authentication flows which are needed -

1. Web application/ SPA client – Has a separate BFF (Backend for frontend) server so that Access and refresh tokens are stored securely on the server-side within the BFF.
2. First Party Mobile App/Desktop Clients – uses the Authorization Challenge Endpoint with Sender constrained tokens with DpOP (demonstrating proof of possesion) and additionally device binding.
3. Service to Service API – uses Client credentials grant for confidential clients (RFC 6749) with additional mTLS support (RFC 8705)
4. SMART-on-FHIR - Essentially client-credentials with signed JWT assertions (system-to-system FHIR access).
5. Proposed flows

• Device Authorization Grant (“device code”)

For kiosks, TVs in waiting rooms, imaging consoles, ward tablets without full browser.

• CIBA (Backchannel auth)

For decoupled approvals (e.g., clinician approves on phone while action originates elsewhere).

This is a really good list. Starting with Service to Service API as this is the most urgent need, but I could see us tackling the others on this list as the demand for them is apparent.

Delegating token issuance to Keycloak/Okta/Entra makes a lot of sense, but many healthcare deployments still want an in-house authorization control plane for org/hospital membership, role assignment, department/group constraints, and audit governance — even if authentication is federated. Otherwise the operational pressure is to encode hospital semantics into IdP roles/groups, which tends to get brittle. Maybe Your AuthorizationPolicy + TenantResolver looks like exactly the right place to plug that in.

Hospitals make an org-level IT decision on their identity platform, and HFS just needs to plug into it. AuthorizationPolicy + TenantResolver for us are the parts that can do that.

Client registry “not in HFS” is fine — but healthcare still needs a registry somewhere, Not necessarily in HFS, but you still need a source of truth for:

• which clients map to which org/hospital(s)
• what compartment filters apply
• which AI agents are allowed to read which facilities

Yes - that source of truth belongs in the TenantResolver, which is responsible for mapping a validated client_id to its organizational context.