work-with-auth

Configure and validate SMART-on-FHIR OAuth2 JWT bearer authentication for HFS.

51|19|Updated Jan 4, 2025
One-click install
npx skills add https://github.com/HeliosSoftware/hfs --skill work-with-auth-heliossoftware
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: work-with-auth
Source: https://github.com/HeliosSoftware/hfs/tree/main/.agents/skills/work-with-auth
Command: npx skills add https://github.com/HeliosSoftware/hfs --skill work-with-auth-heliossoftware

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Working on HFS authentication and authorization requires understanding how the helios-auth crate validates SMART-on-FHIR/OAuth2 JWT bearer tokens, enforces scopes, and resolves tenants, which is spread across many modules and environment variables. ## Core Features & Use Cases - JWT Bearer Validation: Configure JWKS-based token signature verification with issuer, audience, and algorithm checks via HFS_AUTH_* environment variables. - SMART v2 Scope Enforcement: Work with SmartScopePolicy, ScopeSet, and SmartPermissions to enforce scopes like system/Patient.rs. - SMART Discovery: Serve /.well-known/smart-configuration populated from HFS_SMART_* endpoint settings. - Use Case: When modifying token replay semantics or adding a new scope check in helios-auth, use this Skill to navigate config.rs, provider/, jwks/, scope/, and policy/ modules and understand why jti replay caching must not be reintroduced. ## Quick Start Ask the AI to help you modify or debug HFS authentication behavior, such as adding a new SMART scope check or configuring JWKS validation in the helios-auth crate.

Frequently Asked Questions about work-with-auth

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enable JWT bearer authentication in HFS?▼

Set HFS_AUTH_ENABLED=true and configure HFS_AUTH_JWKS_URL pointing to your identity provider's JWKS endpoint. Optionally set HFS_AUTH_ISSUER and HFS_AUTH_AUDIENCE to validate the iss and aud claims of incoming tokens.

How does HFS enforce SMART on FHIR scopes?▼

HFS enforces SMART v2 scopes such as system/Patient.rs through SmartScopePolicy, ScopeSet, and SmartPermissions in the helios-auth crate. Scope logic lives in the scope/ and policy/ modules and is consumed by helios-rest, helios-hfs, and helios-subscriptions.

Does HFS cache JWT jti values to prevent token replay?▼

No, HFS intentionally has no jti replay cache because bearer access tokens are reusable until expiry. Single-use jti semantics apply only to private_key_jwt client assertions, which the authorization server enforces, not the resource server.

Which JWT signing algorithms does HFS support?▼

HFS accepts RS256, RS384, ES256, and ES384 by default via the HFS_AUTH_ALGORITHMS setting. You can override this list to restrict or extend the allowed signing algorithms for token validation.

How does HFS resolve the tenant from a JWT?▼

HFS derives the tenant from a JWT claim configured by HFS_AUTH_TENANT_CLAIM, which defaults to tenant_id. Validation is fully local, so multiple instances behind a load balancer need no shared state.