| name | work-with-auth |
| description | Work on HFS authentication & authorization. Use for SMART-on-FHIR/OAuth2, JWT bearer validation, JWKS, scopes/permissions, token replay semantics, SMART discovery, and HFS_AUTH_* configuration. |
Authentication & Authorization
Use this when working in helios-auth or HFS auth behavior. The crate validates SMART-on-FHIR / OAuth2 JWT bearer tokens and enforces scopes. It is consumed by helios-rest, helios-hfs, and helios-subscriptions.
Behavior
- Disabled by default. Set
HFS_AUTH_ENABLED=true to require bearer tokens.
- Validates JWTs against a JWKS endpoint (
HFS_AUTH_JWKS_URL), checking issuer, audience, and signing algorithm.
- Enforces SMART v2 scopes (e.g.
system/Patient.rs) via SmartScopePolicy / ScopeSet / SmartPermissions.
- Derives the tenant from a JWT claim (
HFS_AUTH_TENANT_CLAIM, default tenant_id).
- Serves
/.well-known/smart-configuration (SMART discovery), populated from the HFS_SMART_* endpoints.
- Holds no cross-instance state: validation is local, so instances behind a load balancer need no shared infrastructure.
Environment
| Variable | Default | Description |
|---|
HFS_AUTH_ENABLED | false | Require bearer-token auth |
HFS_AUTH_JWKS_URL | none | JWKS endpoint for token signature verification |
HFS_AUTH_ISSUER | none | Expected iss |
HFS_AUTH_AUDIENCE | none | Expected aud |
HFS_AUTH_ALGORITHMS | RS256,RS384,ES256,ES384 | Allowed signing algorithms |
HFS_AUTH_TENANT_CLAIM | tenant_id | JWT claim used to resolve the tenant |
HFS_AUTH_JWKS_MIN_REFRESH_INTERVAL | 10 | Minimum seconds between JWKS refreshes |
SMART discovery passthrough (advertised in /.well-known/smart-configuration): HFS_SMART_TOKEN_ENDPOINT, HFS_SMART_AUTHORIZE_ENDPOINT, HFS_SMART_JWKS_URL, HFS_SMART_INTROSPECTION_ENDPOINT, HFS_SMART_MANAGEMENT_ENDPOINT, HFS_SMART_REGISTRATION_ENDPOINT, HFS_SMART_REVOCATION_ENDPOINT. Outbound calls can carry HFS_OUTBOUND_BEARER_TOKEN.
Token replay
There is no jti replay cache — bearer access tokens are accepted as many
times as the client presents them until they expire. Do not reintroduce one
(#205): single-use jti semantics belong to private_key_jwt client assertions
(RFC 7523 §3), which the authorization server's token endpoint enforces. HFS is
a resource server with no token endpoint, so every jti it sees belongs to a
reusable access token (Keycloak and most IdPs emit one on all of them), and
replay-checking it rejects the second and every later use of a perfectly valid
token.
A replay cache cannot defend a bearer token anyway: a replayed one is
byte-identical to a legitimate one. Real anti-replay needs sender-constrained
tokens (DPoP/mTLS), where a fresh per-request proof — not the access token — is
what gets checked. crates/auth/tests/bearer_token_reuse.rs pins this behavior.
Key API
AuthConfig, AuthProvider / JwksBearerAuthProvider, Principal, ScopeSet / SmartPermissions, SmartScopePolicy, JwksCache, SmartConfiguration.
Code map
config.rs, provider/, jwks/ (cache, fetcher), scope/ (smart_v2, permissions), policy/, principal.rs, discovery.rs, outbound.rs. Auth scopes are consumed by Bulk Data Submit (system/bulk-submit). Unit tests are inline in src/; integration tests live under crates/auth/tests/.
Named operation scopes
Some operations are gated on a named scope of their own rather than on resource
permissions, via ScopeSet::grants_operation(name) — which matches a literal
system/{name} or any system/*.<perm> wildcard:
| Scope | Grants |
|---|
system/bulk-submit | $bulk-submit ingestion |
system/purge | $purge — permanent, irreversible deletion of a resource and its history |
system/reindex | $reindex — rebuilding a tenant's entire search index |
These deliberately do not fall out of ordinary resource scopes: a token that
may soft-delete a Patient (system/Patient.d) must not thereby be able to
obliterate it, and a token that may write resources must not be able to rebuild
the search index.
The auth middleware's extract_operation returns None for $purge,
$reindex, and $reindex-status so their handlers can enforce the above — it
would otherwise classify POST /Patient/$purge as a Create on Patient. That
deferral list is a narrow allowlist (HANDLER_AUTHORIZED_OPS in
crates/rest/src/middleware/auth.rs), not a blanket rule for $-paths:
SQL-on-FHIR operations have no handler-level scope check, so exempting every
$-path from middleware classification would leave them entirely unauthorized.
