SMART on FHIR-Frontend Flows

SMART on FHIR established a method for health apps to connect to EHR systems while maintaining adequate security. Components also included authorization, authentication, and UI integration in addition to FHIR models and API.

The core focus of the SMART on FHIR is to make it as easy as for a rich ecosystem of apps to be able to plug in too many different kinds of clinical systems.

Components:

1. A SMART on FHIR app (also known as an application or a service) connects to a SMART on FHIR system and enhances its usefulness by including clinical and contextual data.
2. OAuth2 is a web-based authorization standard. Its primary purpose is to allow an end-user (in this example, a patient or clinician) to authorize a third-party app (such as a SMART app) to access a certain set of data from a service provider (e.g., EHR).
3. OpenID Connect is a Web authentication standard. It specifies an OAuth2-based protocol that enables end-users to sign into apps using third-party identity providers

The launch framework supports the use cases:

1. Patient apps that launch standalone or through the portal

2. Provider apps that launch standalone or through the portal

SMART on FHIR app launch framework enables an entity's permissions (e.g., a user's permissions) to be delegated to a third-party app. A restricted portion of an entity's rights can be delegated using the profile's procedures (e.g., only sharing access to certain data types). It provides no mechanism to specify that a given entity should or should not be able to access specific records in an EHR. As a result, this profile is built to interact with an EHR's current user and permissions management system, allowing for a standardized delegation mechanism.

Security and Privacy Considerations while launching the apps:

1. App Protection: The app is responsible for defending itself from potentially harmful or misbehaving data supplied to its redirect URL as well as unauthorized access and usage of authorization codes, access tokens, and refresh tokens. The app developer must be aware of possible vulnerabilities like malicious applications operating on the same platform, counterfeit authorization servers, and resource servers, and take precautions to secure both the app and any sensitive data it may contain.
2. Support for “public” and “confidential” apps: Confidential app profiles can be used by clients capable of protecting the secrecy of their credentials or securing client authentication via other means. Public app profiles can be used by clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application, who are incapable of maintaining the confidentiality of their credentials and are also incapable of secure client authentication via any other means.
3. Considerations for PKCE Support: All the SMART apps shall support the PKCE (Proof Key for CODE Exchange). It is an extension to the Authorization Code flow to prevent Cross-Site Request Forgery and authorization code injection attacks. PKCE is not a replacement for client authentication, it does not allow treating a public client as a confidential client.

Now let’s have a look at the steps for the SMART App Launch:

The first step in launching an app whether we are launching a standalone or through a portal we need to register the app with the EHR. The registration can be done through OAuth 2.0 Dynamic Client Registration Protocol.

To know more watch the video:

STANDALONE LAUNCH:

A standalone app launch is the launching of an app by a user which is outside of the EHR. In this, you can connect to EHR either by simply clicking on the button on your screen or can be automatically redirected. A Discover API tells that if we query this URL /.well-known/smart-configuration through the "GET" request then you will get the discovery endpoint response.

A JSON document must be returned using the application/json mime-type.

HTTP/1.1 200 OK
Content-Type: application/json
{
	"issuer": "https://ehr.example.com",
	"jwks_uri": "https://ehr.example.com/.well-known/jwks.json",
	"authorization_endpoint": "https://ehr.example.com/auth/authorize",
	"token_endpoint": "https://ehr.example.com/auth/token",
	"token_endpoint_auth_methods_supported": [
		"client_secret_basic",
		"private_key_jwt"
	],
	"grant_types_supported": [
		"authorization_code",
		"client_credentials"
	],
	"registration_endpoint": "https://ehr.example.com/auth/register",

Example Response for /.well-known/smart-configuration

In this, we will be taking into consideration the authorization endpoint. This is just a screen where we will go to authorize the user.

Then after entering the credentials it asks us whether we want to allow the client to only read patients or read and write encounters too. At this time, apps launching the standalone launch flow will not have a launch id. These apps can specify their launch context requirements by including particular scopes in the permission request, such as launch/patient to indicate that the app requires a patient ID. The "authorized" endpoint in the EHR will take care of obtaining the context it requires.

Then you are redirected to the app screen where you need to provide the redirect URL along with the code. Then we post this code to the token endpoint and we get the bearer access token. We can post the with a lot of variation like with PKCE or with backend flow. This is just to prove to the backend server that this code is coming from a legit place.

Location: https://app/after-auth?
code=123abc&
state=98wrghuwuogerg97

Redirect URL with Code

The other way is that is insecure (implicit) flow in which you directly get the token in the beginning and you can use that to make the API calls. This is more insecure than using the PKCE.

EHR APP LAUNCH:

In this, the EHR initiates a launch. The user needs to establish an EHR session first and then decides to launch the app. This app can be a single patient app or a user-level app. The EHR begins this interaction where it sends the user back to the app by opening an inline frame or an embedded window onto that app. Then you will get a launch URL with two parameters.

One is a launch parameter that is an opaque token and the other is the iss(issuer) ie the EHR URL. Now you will follow the same process as above by going to authorize URL but we will also add the launch parameter in that.

Now the EHR launch with a particular patient but if it doesn't launch with a particular patient then we can add it to the scope.

SMART Authorization Scopes:

The scopes help in conveying what access an app needs. We can provide the scope along with launch parameters like launch/patient or launch/encounter. This helps in getting particular information.

Now after selecting we come back to the app and we get a redirect URL along with code. We post the code and we get the bearer token along with other details like patient, encounter, and need a patient banner.

This way you can launch your apps using SMART on FHIR.