| name | smart-app-launch |
| description | Expert guidance for implementing SMART App Launch (HL7 FHIR specification for OAuth 2.0-based authorization). Use this skill when implementing FHIR app authorization, EHR launch sequences, standalone app launch, backend services authentication, SMART scopes, token handling, or capability discovery. Trigger keywords include "SMART", "SMART on FHIR", "EHR launch", "standalone launch", "FHIR authorization", "FHIR OAuth", "backend services", "system scopes", "patient scopes", "fhirUser", ".well-known/smart-configuration", "PKCE", "client_credentials", "launch context". |
SMART App Launch
SMART App Launch provides a standardised OAuth 2.0-based authorization framework for FHIR applications. It enables apps to securely access healthcare data with appropriate user consent and context.
Choosing a launch pattern
Select the appropriate pattern based on your use case:
| Pattern | Use when | Grant type |
|---|
| EHR Launch | App launched from within EHR UI | authorization_code |
| Standalone Launch | App launched independently by user | authorization_code |
| Backend Services | Server-to-server, no user present | client_credentials |
Core workflow
Step 1: Discover server capabilities
Fetch {fhir-base}/.well-known/smart-configuration to discover:
authorization_endpoint and token_endpointcapabilities array (launch modes, client types, permission models)code_challenge_methods_supported (must include S256)
See references/capability-discovery.md for full field reference.
Step 2: Choose client authentication
| Client type | Method | Registration |
|---|
| Public | PKCE only, no secret | client_id only |
| Confidential (symmetric) | Client secret | Secret shared at registration |
| Confidential (asymmetric) | Private key JWT | JWKS URL or keys registered |
Backend services require asymmetric authentication. See references/client-authentication.md.
Step 3: Request authorization
EHR Launch: App receives iss and launch parameters, echoes launch in authorization request.
Standalone Launch: App initiates flow, may request launch/patient or launch/encounter to establish context.
Required authorization parameters:
response_type=codeclient_id, redirect_uri, scope, state (122+ bits entropy)aud (FHIR server base URL)code_challenge + code_challenge_method=S256
See references/app-launch.md for complete flow details.
Step 4: Exchange code for tokens
POST to token endpoint with:
grant_type=authorization_codecode, redirect_uri, code_verifier- Client authentication (if confidential)
Token response includes:
access_token, token_type, scope, expires_in- Optional:
refresh_token, id_token, launch context (patient, encounter)
Step 5: Access FHIR resources
GET {fhir-base}/Patient/123
Authorization: Bearer {access_token}
Scopes quick reference
patient/Observation.rs # Read + search patient observations
user/Appointment.cruds # Full access to user's appointments
system/Patient.rs # Backend service read/search all patients
launch/patient # Request patient context at launch
openid fhirUser # Get user identity via OIDC
offline_access # Request refresh token
Scope syntax: {context}/{resource}.{permissions}[?{constraints}]
See references/scopes.md for complete scope grammar and examples.
Backend services
For server-to-server access without user interaction:
- Register client with JWKS URL
- Create signed JWT assertion with required claims (
iss, sub, aud, exp, jti)
- POST to token endpoint with
grant_type=client_credentials and client_assertion
- Use
system/ scopes only
See references/backend-services.md for JWT structure and examples.
Security requirements
- PKCE with S256 is mandatory for all authorization code flows
- TLS 1.2+ required for all token transmission
- Access tokens should expire within 1 hour (5 minutes for backend services)
- Validate
state parameter to prevent CSRF
- Validate
aud matches your FHIR endpoint
See references/security.md for comprehensive security guidance.
References
