This page is part of the Smart App Launch Implementation Guide (v2.1.0: STU 2.1) based on FHIR R4. This is the current published version in its permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

Overview

Official URL: http://hl7.org/fhir/smart-app-launch/ImplementationGuide/hl7.fhir.uv.smart-app-launch				Version: 2.1.0
Active as of 2021-10-30				Computable Name: SmartAppLaunch

This implementation guide describes a set of foundational patterns based on OAuth 2.0 for client applications to authorize, authenticate, and integrate with FHIR-based data systems. The patterns defined in this specification are introduced in the sections below. For background on SMART Health IT, see smarthealthit.org.

Discovery of Server Capabilities and Configuration

SMART defines a discovery document available at .well-known/smart-configuration relative to a FHIR Server Base URL, allowing clients to learn the authorization endpoint URLs and features a server supports. This information helps client direct authorization requests to the right endpoint, and helps clients construct an authorization request that the server can support.

SMART Defines Two Patterns For Client Authorization

Authorization via SMART App Launch

Authorizes a user-facing client application (“App”) to connect to a FHIR Server. This pattern allows for “launch context” such as currently selected patient to be shared with the app, based on a user’s session inside an EHR or other health data software, or based on a user’s selection at launch time. Authorization allows for delegation of a user’s permissions to the app itself.

Authorization via SMART Backend Services

Authorizes a headless or automated client application (“Backend Service”) to connect to a FHIR Server. This pattern allows for backend services to connect and interact with an EHR when there is no user directly involved in the launch process, or in other circumstances where permissions are assigned to the client out-of-band.

SMART Defines Two Patterns For Client Authentication

When clients need to authenticate, this implementation guide defines two methods.

Note that client authentication is not required in all authorization scenarios, and not all SMART clients are capable of authenticating (see discussion of “Public Clients” in the SMART App Launch overview).

Asymmetric (“private key JWT”) authentication

Authenticates a client using an asymmetric keypair. This is SMART’s preferred authentication method because it avoids sending a shared secret over the wire.

Symmetric (“client secret”) authentication

Authenticates a client using a secret that has been pre-shared between the client and server.

Scopes for Limiting Access

SMART uses a language of “scopes” to define specific access permissions that can be delegated to a client application. These scopes draw on FHIR API definitions for interactions, resource types, and search parameters to describe a permissions model. For example, an app might be granted scopes like user/Encounter.rs, allowing it to read and search for Encounters that are accessible to the user who has authorized the app. Similarly, a backend service might be granted scopes like system/Encounter.rs, allowing it to read and search for Encounters within the overall set of data it is configured to access. User-facing apps can also receive “launch context” to indicate details about the current patient or other aspects of a user’s EHR session or a user’s selections when launching the app.

Note that the scope syntax has changed since SMARTv1. Details are in section Scopes for requesting FHIR resources.

Token Introspection

SMART defines a Token Introspection API allowing Resource Servers or software components to understand the scopes, users, patients, and other context associated with access tokens. This pattern allows a looser coupling between Resource Servers and Authorization Servers.

FHIR Publication Details

Intellectual Property Statements

No use of external IP

Cross Version Analysis

Note: While this publication includes artifacts for FHIR R4, SMART App Launch is compatible with any version of FHIR from DSTU2 and onward.

This is an R4 IG. None of the features it uses are changed in R4B, so it can be used as is with R4B systems. Packages for both R4 (hl7.fhir.uv.smart-app-launch.r4) and R4B (hl7.fhir.uv.smart-app-launch.r4b) are available.

Package Dependencies

Note: While this publication includes artifacts for FHIR R4, SMART App Launch is compatible with any version of FHIR from DSTU2 and onward.

Global Profile Definitions

There are no Global profiles defined