When developing SMART-on-FHIR apps, localhost is the only hostname that reliably works with plain HTTP. This is due to browser security rules and the requirements of the SMART-on-FHIR specification.
Why Localhost Works with HTTP
- Browsers treat
http://localhostas a "secure context". - This allows use of security-sensitive APIs (like the Web Crypto API) and OAuth2 flows without HTTPS.
- You do not need a DNS name or SSL/TLS certificate for local development.
Example: Localhost Launch URL
- Both the app and FHIR server endpoints use
http://localhost. - This enables rapid prototyping and testing.
Moving to Production
When deploying beyond localhost, you must use HTTPS:
- All endpoints must use
https://. - You need a DNS name (e.g.,
app.example.org). - You must install a valid SSL/TLS certificate.
This is required for:
- Browser security (Web Crypto API, OAuth2)
- Compliance with SMART-on-FHIR standards
Summary Table
| Context | Hostname | Protocol | Requirements |
|---|---|---|---|
| Development | localhost | HTTP | No DNS/cert needed |
| Production | custom domain | HTTPS | DNS + valid SSL/TLS cert |
Tip:
Start with http://localhost for development.
Switch to HTTPS and configure DNS/certificates for production.
For more details on launch tokens and context, see ./token-content-analysis.md.