SMART on FHIR: Introduction - Smile CDR Documentation

SMART on FHIR: Introduction

The SMART on FHIR specification is a popular choice for providing a consistent approach to security and data requirements for health applications. SMART on FHIR defines a workflow that an application can use to securely request access to data, and then receive and use that data.

The SMART App Gallery contains many examples of SMART on FHIR apps, and more are being created every day.

In a nutshell, SMART on FHIR can be thought of as three things:

  1. Identity and Access Management: SMART uses the OpenID Connect identity management protocol, which allows applications to request access to clinical data. This access might be simple read-only access to a few records, broad read/write access to an entire EHR, or anything in between. The SMART specifications describe a specific flavour of OpenID Connect that is customized for use in the health context.

  2. Access to Data: SMART uses the FHIR standard for actually reading and/or updating that data. This means that in a SMART on FHIR architecture, a set of FHIR services are available for use by SMART applications. These services are secured using the Identity and Access Management layer described above.

  3. Launch: For web-based applications, SMART describes a consistent URL scheme for portals, EHRs, etc., to use for launching web-based applications with a set of context being passed to the application. This context can include information about the currently selected patient, clinical encounter, styling information, etc.

Platforms

Applications can take many forms:

The SMART Launch Sequence

This section explains how the launch sequence for a SMART on FHIR application actually works.

Underlying Technology

First, let's clarify a few technologies we are using.

Participants

In the SMART on FHIR Authorization process, there are four participants:

The Interactive Launch Process

The following diagram illustrates the sequence of events when a SMART on FHIR application is started.

Step 1: Application Launch

For web-based applications, the user will generally follow a link to the application. This link includes parameters specifying the "launch context".

For example, suppose a SMART on FHIR application has been created for visualizing the trend of a specific lab test over time. The workflow for this application would involve users working in another system (such as an EMR or a clinical portal) and following a link to the application from within a view that is specific to a particular patient. The link to launch the SMART on FHIR application would include details about which patient was being viewed.

Note that this step is optional, and it is only used when the application is being launched by another application. In other architectures (e.g. mobile applications and standalone web applications), the authorization process might not work this way.

The following SMART on FHIR compliant launch URL shows a launch of the example "MyLabViewer" application: https://mylabviewer.com/launch.html?iss=https://try.smilecdr.com:8000/baseR4&launch=wd9833

Note the URL parameters in the example:

In the first step of the launch sequence, the SMART Application will fetch the FHIR Server's SMART Discovery Document. This document is a small JSON document hosted at a predictable URL behind the FHIR server that the SMART Application can use to learn more about the authorization requirements of the FHIR server.

To fetch the discovery document, the application appends /.well-known/smart-configuration to the base URL of the FHIR endpoint. For example: https://try.smilecdr.com:8000/baseR4/.well-known/smart-configuration

This endpoint returns a JSON document similar to the following:

{
  "authorization_endpoint": "https://oidc.example.com/authorize",
  "token_endpoint": "https://oidc.example.com/oauth/token",
  "grant_types_supported": [\
    "authorization_code",\
    "client_credentials"\
  ],
  "code_challenge_methods_supported": [\
    "S256"\
  ],
  "capabilities": [\
    "launch-ehr",\
    "client-public"\
  ]
}

Copy

The discovery document contains two important URLs:

It also advertises:

Both fields are emitted by the SMART Outbound Security Module (when Smile CDR is itself the Authorization Server) and by the SMART Inbound Security Module (when Smile CDR fronts an external Authorization Server).

A Note on the CapabilityStatement SMART App Launch 2.x uses the discovery document above as its only discovery mechanism; the older approach of advertising the OAuth2 endpoints in the server's CapabilityStatement is deprecated in that specification. Smile CDR still populates those CapabilityStatement details, for clients written against SMART App Launch 1.0.

Independently of discovery, many clients read the CapabilityStatement before they authenticate. The HAPI FHIR client does this by default, fetching [base]/metadata when the client is constructed in order to check that the server's FHIR version matches its own. A SMART on FHIR enabled endpoint should therefore serve /metadata without authentication. See FHIR Client Authentication for how to configure this.

Step 2: Request Access

The application directs the user to an OpenID Connect Authorization Server. This process is the same one used in the " Login using Facebook" example above but in this case instead of using Google or Facebook we are using a SMART on FHIR compliant authorization server. The general principle is that the user is passed to a third party website where they are asked to enter credentials (if they aren't already logged in) without the SMART on FHIR application ever knowing what those credentials are.

In the case of web applications, this step generally works by having the user follow a link that temporarily takes the user to the third party authorization server. In the case of mobile applications, a web browser window is temporarily opened on the user's device in order to allow the user to access the authorization server.

When the SMART on FHIR Application directs the user to the authorization server, it also requests a set of " OAuth2 Scopes". These scopes are defined in the SMART on FHIR specification and include the following examples (note that these are only examples, not an exhaustive list). See SMART on FHIR Scopes for a complete list of scopes defined in the specification, and see Smile CDR Supported Scopes for a list of scopes supported by Smile CDR.

Step 3: Receive Tokens

Once the user has successfully authenticated with the Authorization Server, they are directed back to the SMART on FHIR application. As a part of this step, the SMART on FHIR application receives an Access Token, which is a long string of characters that will serve as credentials in the steps below.

At a glance, the access token looks like a long string of random letters and numbers. In reality, it is not random at all. Smile CDR produces access tokens using the JSON Web Token (JWT) format. JWTs (pronounced "jots") are basically a small JSON document that has been digitally signed. The document contains a few small pieces of information about where the token was issued and what application requested it.

In addition to the access token, the user may receive two other tokens:

Step 4: Client Request to Access or Modify Clinical Data

The application may now invoke FHIR services by communicating with the Resource Server. A SMART on FHIR Resource Server is a FHIR server that supports a set of FHIR operations, and requires an Access Token as a part of this request.

The request might be a FHIR search operation for discovering data, or a FHIR create operation for uploading newly created data. The scopes that were requested and granted by the Authorization Server will be used to determine whether the user has appropriate permission to perform the specific function they are invoking.

A sample HTTP request follows. Note the presence of an Authorization header whose value is the string Bearer followed by the access token. For readability, the token has been shortened (real tokens are typically much longer).

GET /Observation?subject=Patient/123

Copy

Step 5: Validate Token

The Resource Server should now validate that the token is acceptable. The token has been digitally signed by the Authorization Server, and by verifying this signature the Resource Server can know that it is legitimate.

The verification uses a public key that can either be provided out-of-band or fetched as required by the Resource Server. This public key matches a private key held by the Authorization Server.

As shown above, the token will take a form similar to the following: eyJraWQiOiJ1b.o_GAe_P5E-y4GrCl.gTYd4is8zAQ (although it will generally be longer than this example). This format is called JWT (JSON Web Token), and libraries are available for most languages that can be used to decode this token. Decoding the token results in a JSON document similar to the following:

{
   "azp":"my-client-id",
   "profile":"http:\/\/example.org:8884\/fhir\/RelatedPerson\/999",
   "iss":"http:\/\/example.org:8884",
   "exp":1516069149,
   "iat":1516069089,
   "jti":"95d12878-dd09-4d61-9930-d4b3cf077ec2"
}

Copy

Each key in this payload is called a " claim", and the claims are defined by the JWT, OAuth2, and OpenID Connect specifications. Note the following:

Step 6 (optional): Introspect Token and Request

The Application may wish to learn more information about the issued tokens. This can include additional details about the user the token was issued for, and information about the token such as its expiration time and associated scopes.

The following example shows a request being made by an Application to an Authorization Server.

POST /oauth/token/introspect

token=eyJraWQiOiJ1b.o_GAe_P5E-y4GrCl.gTYd4is8zAQ

Copy

The following payload shows an example response. Note that the Authorization Server is indicating that the user has been approved for a SMART Patient read scope and several others.

{
  "active": true,
  "scope": "patient/*.read online_access openid profile",
  "client_id": "growth_chart",
  "token_type": "Bearer",
  "exp": 1516069149,
  "iat": 1516069089,
  "iss": "http://localhost:8884"
}

Copy

Note that invalid tokens, or tokens that have been revoked, result in a 200 - OK response with "active": false, as specified in RFC 7662:

{
  "active": false,
  "scope": "",
  "client_id": "",
  "token_type": "",
  "exp": "",
  "iat": "",
  "iss": ""
}

Copy

Step 7: Server Response to Access or Modify Clinical Data

Assuming that the access token has been verified correctly and the token introspection shows that the user has appropriate permissions to perform the desired functions, the server will now respond to the given FHIR query.

The following example shows a FHIR query using an access token issued by the Authorization Server:

GET /Patient/123

Copy

SMART on FHIR: Introduction

SMART on FHIR

SMART on FHIR: Introduction SMART: Scopes SMART: Auth Flows SMART: Endpoints SMART: Smile CDR Support SMART Outbound Security: Module SMART Outbound Security: Skinning SMART Outbound Security: Context Selection SMART Outbound Security: SAML Bridging SMART: Federated OAuth2/OIDC Login SMART: Application Approval/Consent SMART Inbound Security Module SMART Client Definitions SMART Server Definitions SMART OIDC Keystore Definitions SMART: Session Management SMART: Assigning Permissions SMART: Access Tokens SMART: User Profile Information FHIR Client Authentication SMART: Machine to Machine Authentication

SMART: Scopes