aehrc/smart-app-launch

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_endpoint
• capabilities 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=code
• client_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_code
• code, 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:

1. Register client with JWKS URL
2. Create signed JWT assertion with required claims (iss, sub, aud, exp, jti)
3. POST to token endpoint with grant_type=client_credentials and client_assertion
4. 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

• references/app-launch.md - EHR and standalone launch flows
• references/scopes.md - Scope syntax and permissions
• references/backend-services.md - System-to-system authentication
• references/client-authentication.md - Authentication methods
• references/capability-discovery.md - .well-known endpoint
• references/security.md - Best practices and security