SMART on FHIR

This guide describes how to use Descope to support SMART on FHIR authorization workflows in healthcare applications. SMART on FHIR is a healthcare industry standard for allowing third-party applications to securely access Electronic Health Record (EHR) data using OAuth 2.0 and OpenID Connect. Descope can help power the authorization, consent, and scope management parts of this flow.

Overview

SMART on FHIR provides a standardized way for healthcare applications to:

• Launch within an EHR system
• Request access to patient data
• Handle user authentication and authorization
• Manage data access scopes

Descope supports both EHR Launch and Standalone Launch flows through its Inbound Apps feature, which provides:

• /authorize endpoint for user authentication and consent
• /token endpoint for token exchange
• JWT templates for customizing access tokens
• Scope management and validation

What the Authorization Flow Looks Like

A typical SMART on FHIR authorization flow with Descope looks like this:

1. The user launches the EHR app and sends a request with key parameters like iss and launch context.
2. Your API Gateway receives this request, caches the parameters, and forwards the request to a handler app.
3. The handler app constructs a request to the Descope /authorize endpoint.
4. The user authenticates through Descope and provides consents for the requested scopes.
5. Descope issues an authorization code, which is then exchanged for an access token via the Inbound App's /token endpoint.
6. The access token, along with scopes authorized, is returned to the handler. The handler adds any additional required context, and then forwards the response to the app.

Integration Steps

Let's go over the configurations within Descope you'll need to set up to support this flow.

1. Configure Your Inbound App in Descope

1. In the Descope Console, navigate to the Inbound Apps tab. Click + Inbound App on the top right.

2. Configure the required permissions scopes for your SMART app. Your SMART app will generally require some of the following scopes:

   • patient/*.rs - Permission to read and search any resource for the current patient
   • launch - Permission to obtain launch context when app is launched from an EHR
   • openid and fhirUser - Permission to retrieve information about the current logged-in user

   For more common scopes, refer to the FHIR documentation.

3. Set the redirect URI to your application's URL

4. Customize your consent flow

2. Configure JWT Template

Set up a JWT template in Descope to handle FHIR authentication:

1. Create a new JWT template in your Descope project
2. Configure the aud claim to be the URL of the EHR resource server from which the app wishes to retrieve FHIR data
3. Under Session Management in the Descope Console Project Settings, assign User JWT to your new JWT Template

Conclusion

With Descope and SMART on FHIR configured:

• Your app can now securely launch from an EHR or as a standalone application.
• Users will be prompted to log in and grant consent using a customizable Descope Flow
• Descope will issue an access token that includes the required SMART claims and scopes
• You can forward this token to the EHR’s FHIR server to access protected healthcare data on behalf of the user

By managing authentication, consent, and access token generation with Descope, you can stay focused on building healthcare applications—without worrying about implementing the OAuth 2.0 mechanics from scratch.