SMART on FHIR Security: OAuth 2.0 and OIDC
While the FHIR standard beautifully standardizes the data schema and the RESTful API transport mechanism, it intentionally does not dictate how applications authenticate users or authorize access.
This critical security gap is elegantly bridged by the SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR framework.
Industry Standard
SMART on FHIR has become the industry standard for secure FHIR API access, supported by Epic, Cerner, and all major EHR vendors.
SMART on FHIR Specification
Official HL7 SMART on FHIR app launch and authorization specification
View SMART SpecSMART on FHIR Architecture
SMART on FHIR layers industry-standard identity protocols directly on top of FHIR RESTful interfaces.
Core Protocols
- OAuth 2.0: Authorization framework
- OpenID Connect (OIDC): Identity layer
- PKCE: Proof Key for Code Exchange
- JWT: JSON Web Tokens
Authentication Delegation
Architecturally, this framework delegates the highly sensitive authentication process directly to the EHR's native identity provider, ensuring consistent security policies across all integrated applications.
SMART on FHIR OAuth 2.0 authorization flow
Loading diagram...
OpenID Connect (OIDC): Identity Layer
OpenID Connect (OIDC) provides the identity layer on top of OAuth 2.0, enabling user authentication and identity verification.
ID Token Structure
OIDC ID token claims and structure
| Claim | Description | Example |
|---|---|---|
| iss (Issuer) | URL of the authorization server that issued the token | https://auth.epic.com |
| sub (Subject) | Unique identifier for the authenticated user | patient/12345 or practitioner/67890 |
| aud (Audience) | Intended recipient of the token (client_id) | app-client-id-12345 |
| exp (Expiration) | Token expiration time (Unix timestamp) | 1709856000 |
| iat (Issued At) | Time when token was issued (Unix timestamp) | 1709852400 |
| auth_time | Time when user authentication occurred | 1709852300 |
UserInfo Endpoint
The UserInfo endpoint returns claims about the authenticated user as a JSON object. Applications can request additional user attributes beyond what's included in the ID token.
Session Management
- ID tokens are short-lived (typically 1 hour)
- Refresh tokens enable silent re-authentication
- Logout endpoint invalidates user session
- Back-channel logout notifies apps of session termination
Healthcare Identity
In healthcare contexts, OIDC tokens include practitioner role, organization affiliation, and NPI numbers for audit trail and access control.
OIDC Core Specification
OpenID Connect Core 1.0 specification with ID token and UserInfo details
View OIDC SpecAWS Cognito OIDC
AWS Cognito implementation of OpenID Connect for user authentication
Explore Cognito OIDCNASH PKI: Australian Healthcare Authentication
The National Authentication Service for Health (NASH) PKI provides secure organization authentication for Australian healthcare systems.
NASH PKI Components
NASH PKI architecture components
| Component | Purpose | Use Case |
|---|---|---|
| NASH Certificate | Organization identity verification | Authenticate with My Health Record, HI Service |
| Mutual TLS (mTLS) | Bidirectional certificate authentication | Secure B2B gateway connections |
| HPI-O | Healthcare Provider Identifier-Organisation | Unique organization identifier linked to certificate |
| Certificate Authority | Australian Digital Health Agency PKI | Issue and manage NASH certificates |
Mutual TLS (mTLS) Authentication
NASH certificates enable mutual TLS authentication where both client and server verify each other's certificates. This provides strong bidirectional authentication for B2B healthcare integrations.
Integration with National Services
- My Health Record B2B Gateway
- Healthcare Identifiers (HI) Service
- Digital Health Certificate Service
- Secure Messaging (Healthmail)
Certificate Management
NASH certificates must be renewed annually and securely stored. Compromised certificates must be immediately revoked through the Australian Digital Health Agency.
NASH PKI Certificate Policy
Australian Digital Health Agency NASH PKI certificate program
View NASH PKIHI Service Integration
Healthcare Identifiers Service for patient and provider identification
Explore HI ServiceMy Health Record B2B
B2B integration guide for My Health Record with NASH authentication
Learn MHR IntegrationAWS Security Services for Healthcare
AWS provides HIPAA-eligible security services for implementing SMART on FHIR architectures.
Core Security Services
AWS security services for SMART on FHIR
| Service | Purpose | Feature |
|---|---|---|
| Amazon Cognito | User authentication and authorization | User pools, identity pools, MFA support |
| AWS IAM | Service account access control | Roles, policies, least privilege enforcement |
| AWS KMS | Encryption key management | HIPAA-eligible key storage, key rotation |
| AWS CloudTrail | Audit logging and compliance | API call logging, event history, S3 integration |
| AWS Secrets Manager | Secure credential storage | Automatic rotation, encryption, access control |
Cognito User Pools
Amazon Cognito provides managed user directories with support for OAuth 2.0, OIDC, and SAML. Features include multi-factor authentication (MFA), password policies, and user migration capabilities.
IAM Roles for Service Accounts
AWS IAM enables fine-grained access control for service-to-service authentication. IAM roles can be assumed by EC2 instances, Lambda functions, and ECS tasks without managing credentials.
HIPAA Compliance
AWS offers a HIPAA-eligible services program. Cognito, KMS, CloudTrail, and Secrets Manager can all be used for PHI workloads with proper BAA in place.
AWS Cognito for Healthcare
Amazon Cognito user authentication and authorization for healthcare applications
View CognitoPKCE: Proof Key for Code Exchange
To prevent malicious token interception during the OAuth sequence, especially for public mobile clients, the architecture strictly mandates the use of Proof Key for Code Exchange (PKCE).
PKCE Protection
- Generates code verifier (random string)
- Creates code challenge (hashed verifier)
- Sends challenge with authorization request
- Sends verifier with token request
- Server validates verifier matches challenge
- Prevents authorization code interception
Mobile Security
PKCE is essential for mobile and single-page applications that cannot securely store client secrets, preventing man-in-the-middle attacks.
OAuth Security Best Practices
RFC 6819 - OAuth 2.0 threat model and security considerations
Read RFC 6819Granular Scopes: Least Privilege
The defining, revolutionary feature of SMART on FHIR is its implementation of highly granular clinical data scopes.
Principle of Least Privilege
Rather than granting a third-party application unfettered access to an entire clinical repository, the OAuth sequence restricts access contextually based on precise operational needs.
Common SMART Scopes
SMART on FHIR scopes and access levels
| Scope | Access | Use Case |
|---|---|---|
| patient/Patient.read | Read patient demographics | Patient identification, registration |
| patient/Observation.read | Read clinical observations | Lab results, vital signs review |
| patient/MedicationRequest.read | Read medication prescriptions | Medication reconciliation |
| patient/AllergyIntolerance.read | Read allergy information | Medication safety checks |
| patient/Condition.read | Read diagnoses and conditions | Problem list review |
| user/*.read | Read all resources for logged-in user | Clinician workflow applications |
Security Benefit
If an application only needs to review drug allergies, it requests patient/AllergyIntolerance.read scope—fundamentally securing the ecosystem against unauthorized data exposure.
FHIR Access Control
HL7 FHIR access control and authorization implementation guidance
View Access ControlJWT: JSON Web Tokens
Upon user approval of the transparent consent prompt, the application receives a JSON Web Token (JWT).
JWT Structure
- Header: Algorithm and token type
- Payload: Claims (scope, patient, user, expiry)
- Signature: Cryptographic verification
Token Usage
The JWT only permits API calls matching the precise scope approved by the user. Each FHIR request includes the token in the Authorization header.
JWT Best Practices for Healthcare
SMART on FHIR backend-services guidance showing JWT client assertions and asymmetric authentication flows.
SMART JWT GuidanceSecurity Components Summary
The following table summarizes the key security components of SMART on FHIR.
SMART on FHIR security components
| Component | Purpose | Function |
|---|---|---|
| OAuth 2.0 | Authorization framework | Delegated access control with scoped permissions |
| OpenID Connect (OIDC) | Identity layer on OAuth 2.0 | User authentication and identity verification |
| PKCE | Code exchange security | Prevents authorization code interception attacks |
| JWT | Token format | Signed, verifiable access tokens with claims |
| Scopes | Access granularity | Principle of least privilege enforcement |
NIST Cybersecurity Framework
NIST framework for improving critical infrastructure cybersecurity
View NIST FrameworkHealthcare Cybersecurity
HHS resources on healthcare industry cybersecurity practices
Explore HHS SecuritySecurity Best Practices
Implementing SMART on FHIR requires adherence to security best practices.
Application Development
- Request minimum necessary scopes
- Implement PKCE for all public clients
- Securely store tokens (never in localStorage)
- Handle token refresh automatically
- Validate JWT signatures
- Implement proper error handling
EHR Integration
- Register applications in EHR developer portal
- Configure redirect URIs precisely
- Implement transparent consent prompts
- Log all authorization events
- Monitor for anomalous access patterns
App Registration Guide
SMART Health IT guide for registering applications with EHR vendors
View Registration GuideSummary & Key Takeaways
SMART on FHIR provides industry-standard security for FHIR APIs through OAuth 2.0, OIDC, and PKCE.
Core Concepts Recap
- SMART: Substitutable Medical Applications, Reusable Technologies
- OAuth 2.0: Delegated authorization framework
- OIDC: Identity verification layer
- PKCE: Prevents code interception (mandatory for mobile)
- Scopes: Granular access control (least privilege)
- JWT: Signed access tokens with claims
Security Benefits
- Authentication delegated to EHR identity provider
- Granular scopes prevent over-permissioning
- PKCE protects mobile and public clients
- JWT enables verifiable, stateless authorization
- Transparent consent prompts inform users
Next Steps
Proceed to Migration Patterns to explore FHIR Façade, MPI algorithms, and CDR architecture for legacy system integration.
External References
For further reading on SMART on FHIR security and OAuth 2.0:
NIST Cybersecurity Framework
NIST healthcare cybersecurity guidance and framework for protecting health information
View NIST FrameworkSMART on FHIR Specification
Official HL7 SMART on FHIR app launch and authorization specification
Read SMART on FHIR SpecOAuth 2.0 for Healthcare
OAuth 2.0 authorization framework documentation for secure API access
Learn OAuth 2.0AWS Secrets Manager
AWS service for securely storing and rotating API keys, OAuth tokens, and database credentials for healthcare applications
Explore AWS Secrets ManagerAWS IAM for Healthcare
AWS Identity and Access Management for fine-grained access control and least privilege enforcement in healthcare workloads
View AWS IAMKnowledge Check
Test your understanding with this quiz. You need to answer all questions correctly to mark this section as complete.