FHIR® Service Authorization Specification v1.0


Overview

SMART® on FHIR® is a framework designed to enable the secure integration of applications with Electronic Health Records, portals, Health Information Exchanges, and other Health IT systems via the HL7® FHIR® Standard standard. This document codifies a formal technical specification, based upon the open source SMART® on FHIR® framework. This specification is targeted at both client application developers and developers of Electronic Health Records for securely consuming and securely offering FHIR® services, respectively.

License

This document is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

Introduction

Within the health-care environment, multiple actors may be involved with an individual’s health record. When an application needs to access data in a electronic health record via a FHIR® service, it may need to interact (directly or indirectly) with one or more of these actors to obtain authorization to perform work.

The SMART® on FHIR® framework standardizes the mechanisms under which an application obtains authorization to the following types of resources:

To orchestrate this interaction, SMART® on FHIR® defines a set of authorization profiles and extensions for the OAuth 2.0 Authorization Framework (IETF RFC 6749).

Terminology

The following terms are used within this specification:

Notational Convention

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Unless otherwise noted, all the protocol parameter names and values are case sensitive.

Specification

SMART® on FHIR® describes the following types of workflows:

Contextless Flow

+---------------+                                 +---------------+
|               |                                 |               |
| Resource      +-(1)-----------------------------> SMART         |
| Owner         |                                 | Application   |
|               |        +---------------+        |               |
|               |        |               |        |               |
|               <-(5)----+ Authorization <-(4)----+               |
|               |        | Server        |        |               |
|               +-(6)---->               +-(7)---->               |
|               |        |               |        |               |
+---------------+        |               <-(8)----+               |
                         |               |        |               |
                         |               +-(9)---->               |
                         |               |        |               |
                         +---------------+        |               |
                                                  |               |
                         +---------------+        |               |
                         |               |        |               |
                         | FHIR Resource <-(2)----+               |
                         | Server        |        |               |
                         |               +-(3)---->               |
                         |               |        |               |
                         |               <-(10)---+               |
                         |               |        |               |
                         |               +-(11)--->               |
                         |               |        |               |
                         +---------------+        +---------------+

Figure 1: SMART Application Contextless Flow Diagram

In Figure 1, the following workflow is described:

  1. The end user begins a workflow in the SMART application that requires access to FHIR® resources. The SMART application has either been pre-configured to work with a specific FHIR® resource server, or the user has instructed the SMART application as to the location of the FHIR® resource server, or the application is accessing a record it had previously accessed.
  2. The SMART application performs discovery by requesting the FHIR® server’s conformance statement.
  3. The FHIR® server returns the conformance statement, which provides the needed endpoints for steps 4 and 8.
  4. The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint via a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR® resource.
  5. The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
  6. The end user provides any information needed by the authorization server to proceed.
  7. An authorization grant is sent via the OAuth 2.0 framework back to the SMART application.
  8. The SMART application requests an access token using the authorization code.
  9. The authorization server returns the access token.
  10. The SMART application utilizes the access token to request a FHIR® resource.
  11. The FHIR® resource server returns the desired resource.

Usage

The contextless flow constitutes the most basic use of SMART workflows; it is used where the FHIR® resource needed by the SMART application is already known. Examples of such scenarios include:

Authorization Request

SMART applications SHALL utilize an authorization code grant to request authorization to FHIR® resources. A SMART application SHOULD request scopes needed to access the resource (per the scopes section) for maximum interoperability.
The application MAY choose to omit the redirect URI, as SMART registration requires a default redirect URI.

In addition, SMART applications MUST send the “state” parameter, as detailed in the OAuth 2.0 Security Considerations.

SMART applications that are written natively for a platform SHOULD utilize the operating system’s default browser when performing the authorization request such that the authorization server may comply with any security controls that have been imparted upon it. Such controls may include:

Such “native” applications MAY support orchestrating the authorization flow in an embedded browser where requested out-of-band by the EHR provider.

Authorization Response

Authorization servers SHALL return an OAuth 2.0 authorization code grant to exchange authorization with the SMART application. Authorization servers MAY choose to ask the end user for explicit approval to allow the SMART application to complete this workflow.

Access Token Request

SMART applications SHALL utilize an access token request as described in the section 4.1.3 of OAuth 2.0. The authorization server MAY conditionally require client authentication, depending on the use case.

Access Token Response

Authorization servers SHALL utilize an access token response as described in section 4.1.4 of OAuth 2.0 to respond to the SMART application’s request. As part of the token response, authorization servers SHALL support the return of an id_token where requested and authorized containing a minimal set of identity data, as described in the section “User Identity”.

Authorization servers SHALL include the expires_in parameter to allow SMART applications to be proactive in retrieving new access tokens where necessary.

Authorization servers SHALL return a token type of “bearer” as defined in RFC 6750.

Resource Server Request

To call a FHIR® resource, SMART applications SHALL send the bearer token as an authorization header, as defined in section 2.1 of RFC 6750.

EHR Launch Flow

+---------------+        +---------------+        +---------------+
|               |        |               |        |               |
| Resource      +-(1)----> EHR           +-(2)----> SMART         |
| Owner         |        | Application   |        | Application   |
|               |        |               |        |               |
|               |        +---------------+        |               |
|               |                                 |               |
|               |        +---------------+        |               |
|               |        |               |        |               |
|               <-(6)----+ Authorization <-(5)----+               |
|               |        | Server        |        |               |
|               +-(7)---->               +-(8)---->               |
|               |        |               |        |               |
+---------------+        |               <-(9)----+               |
                         |               |        |               |
                         |               +-(10)--->               |
                         |               |        |               |
                         +---------------+        |               |
                                                  |               |
                         +---------------+        |               |
                         |               |        |               |
                         | FHIR Resource <-(3)----+               |
                         | Server        |        |               |
                         |               +-(4)---->               |
                         |               |        |               |
                         |               <-(11)---+               |
                         |               |        |               |
                         |               +-(12)--->               |
                         |               |        |               |
                         +---------------+        +---------------+

Figure 2: EHR Launch Flow Diagram

In Figure 2, the following workflow is described:

  1. The end user selects to launch a SMART application from within an EHR application.
  2. The EHR directs the user to a URI endpoint registered for the SMART application containing a reference to the current context information, and the location of the EHRs FHIR® API.
  3. The SMART application performs discovery by requesting the FHIR® server’s conformance statement.
  4. The FHIR® server returns the conformance statement, which provides the needed endpoints for steps 5 and 9.
  5. The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint via a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR® resource.
  6. The authorization server interacts with the resource owner to verify identity or other information required by the authorization server.
  7. The end user provides any information needed by the authorization server to proceed.
  8. An authorization grant is sent via the OAuth 2.0 framework back to the SMART application.
  9. The SMART application requests an access token using the authorization code.
  10. The authorization server returns the access token.
  11. The SMART application utilizes the access token to request a FHIR® resource.
  12. The FHIR® resource server returns the desired resource.

EHR Launch Request

In the EHR application launch flow, the end user chooses to “launch” a SMART application from the EHR. To receive such a launch, the SMART application implements an endpoint at a specific URI that accepts the following query parameters:

Normative example:

https://example.org/launch?iss=https%3A%2F%2Fehr%2FFHIR&launch=ef1e6860-db06-4572-b311-02881d01d03d

The syntax for such launch codes are defined in appendix A.3., and for the “iss” value is defined in appendix A.4.

Authorization Request

Upon receipt of a launch context, a SMART application SHALL initiate an authorization grant request to the EHR’s authorization server as previously described in “Contextless Flow”. The SMART application SHALL include the following extension parameters along with the request:

In addition, the SMART application MUST include the scope of “launch” as indicated in “scopes”.

Authorization Response

Authorization servers SHALL return an OAuth 2.0 authorization code grant to exchange authorization with the SMART application. Authorization servers SHOULD reject the request if the authorization code is not associated with the current user. This step prevents cross-site request forgery of SMART application launches.

Upon successful authorization, the authorization server SHALL associate the resulting authorization code with the context information associated with the launch code for retrieval via an access token request.

Access Token Request

SMART applications SHALL utilize an access token request as described in the section 4.1.3 of OAuth 2.0.

Access Token Response

When the SMART application exchanges the authorization code for an access token, the authorization server SHALL return the associated context information as parameters in the token response. The following custom parameters are defined by this specification:

Parameter Example value Meaning
patient “123” String value with a patient id, indicating that the launched was in the context of FHIR® Patient 123. All scopes with resource context of “patient” will be constrained to Patient 123.
encounter “123” String value with an encounter id, indicating that the launch was in the context of FHIR® Encounter 123.
resource “MedicationPrescription/123” String value with a relative resource link, describing some specific resource context for the (in this case, a particular medication prescription). This is a generic mechanism to communicate to an application that a particular resource is “of interest” at launch time.
intent “reconcile-medications” String value describing the intent of the application launch.
Launch Intent

Some SMART applications might offer more than one context or user interface that can be accessed during the EHR launch. An authorization server MAY include the intent parameter to communicate the specific user interface that the SMART application should display.

Launch intent values are not defined by this specification, but most conform to the syntax defined in appendix A.5. Launch Intent Syntax. Such values and their associated semantics are decided via out-of-band agreement between SMART applications and EHR implementations.

Resource Server Request

SMART applications utilize the bearer token from the token response as described previously in “Contextless Flow” to access resources.

SMART Application Launch Flow

+---------------+                                 +---------------+
|               |                                 |               |
| Resource      +-(1)-----------------------------> SMART         |
| Owner         |                                 | Application   |
|               |        +---------------+        |               |
|               |        |               |        |               |
|               <-(5)----+ Authorization <-(4)----+               |
|               |        | Server        |        |               |
|               +-(6)---->               +-(7)---->               |
|               |        |               |        |               |
+---------------+        |               <-(8)----+               |
                         |               |        |               |
                         |               +-(9)---->               |
                         |               |        |               |
                         +---------------+        |               |
                                                  |               |
                         +---------------+        |               |
                         |               |        |               |
                         | FHIR Resource <-(2)----+               |
                         | Server        |        |               |
                         |               +-(3)---->               |
                         |               |        |               |
                         |               <-(10)---+               |
                         |               |        |               |
                         |               +-(11)--->               |
                         |               |        |               |
                         +---------------+        +---------------+

Figure 3: SMART Launch Flow Diagram

In Figure 3, the following workflow is described:

  1. The end user selects an option in a SMART application to retrieve context from the EHR application.
  2. The SMART application performs discovery by requesting the FHIR® server’s conformance statement. The mechanism for how the SMART application is provided the URL for the FHIR® server is not defined by this specification.
  3. The FHIR® server returns the conformance statement, which provides the needed endpoints for steps 4 and 8.
  4. The SMART application creates an OAuth 2.0 authorization grant request, then directs the end user to the authorization server’s authorization endpoint via a browser with said request. This request contains a request for the appropriate scopes necessary to access the FHIR® resource, along with scopes to request the specific types of context information that is desired.
  5. The authorization server extrapolates the current context within the EHR for the user. This may involve direct interaction with the user to confirm such context, or to prompt the user to establish context, and/or to authenticate the user.
  6. The user confirms or establishes the necessary context for the authorization server.
  7. An authorization grant is sent via the OAuth 2.0 framework back to the SMART application.
  8. The SMART application requests an access token using the authorization code.
  9. The authorization server returns the access token.
  10. The SMART application utilizes the access token to request a FHIR® resource.
  11. The FHIR® resource server returns the desired resource.

Authorization Request

In the SMART application launch flow, the end user initiates an action in a SMART application that requires access to context within the EHR. The SMART application in some way is supplied the base URL for the FHIR® service of the EHR; the details of such provisioning is not defined by this specification. After performing discovery, the SMART application SHALL initiate an authorization grant request to the EHR’s authorization server as described previously in “Contextless Flow”.

The SMART application SHALL include one or more scopes that convey the information that is needed for launch as defined in scopes.

Authorization Response

The authorization server shall return a response as described in “Contextless Flow”.

Upon successful authorization, the authorization server SHALL associate the resulting authorization code with the current context information.

Access Token Request

SMART applications SHALL utilize an access token request as described in the section 4.1.3 of OAuth 2.0.

Access Token Response

The authorization server returns a response as described previously in “Contextless Flow”.

Resource Server Request

SMART applications utilize the bearer token from the token response as described previously in “Contextless Flow” to access resources.

Client Credentials Flow

+---------------+        +---------------+
|               |        |               |
| Authorization <-(3)----+ SMART         |
| Server        |        | Application   |
|               +-(4)---->               |
|               |        |               |
+---------------+        |               |
                         |               |
+---------------+        |               |
|               |        |               |
|               <-(1)----+               |
| FHIR Resource |        |               |
| Server        +-(2)---->               |
|               |        |               |
|               <-(5)----+               |
|               |        |               |
|               +-(6)---->               |
|               |        |               |
+---------------+        +---------------+

Figure 4: Client Credentials Flow Diagram

In Figure 4, the following workflow is described:

  1. The SMART application performs discovery by requesting the FHIR® server’s conformance statement. The mechanism for how the SMART application is provided the URL for the FHIR® server is not defined by this specification.
  2. The FHIR® server returns the conformance statement, which provides the needed endpoint for step 3.
  3. The SMART application requests an access token using its client credentials.
  4. The authorization server returns the access token.
  5. The SMART application utilizes the access token to request a FHIR® resource.
  6. The FHIR® resource server returns the desired resource.

Access Token Request

SMART applications SHALL utilize an access token request as described in section 4.4.3 of OAuth 2.0.
The application MUST include credentials; it is RECOMMENDED that authorization servers support “basic authentication” per RFC 2617, and MAY offer other authentication mechanisms to clients.

Access Token Response

The authorization server returns a response as described previously in “Contextless Flow”.

Resource Server Request

SMART applications utilize the bearer token from the token response as described previously in “Contextless Flow”.

Scopes

To obtain access to resources, an application must request the set of scopes necessary for it to perform work on behalf of the end user. The SMART on FHIR® framework describes four distinct collections of scopes: resource access, access to identity information, requests for “launch” information, and longevity modifiers.

Resource Access

A request to access a collection of FHIR® resources consists of one or more SMART scopes. Each SMART scope is constructed per the structure defined in appendix A.1., and contains the following elements:

Resource Context

Three contexts are defined as follows:

Resource Type

The resource type of a resource scope must conform with a valid resource type as defined in the FHIR® Resource Index.

Modification Rights

Three modifications rights are defined:

Examples

The following are normative examples of the resource scopes:

Scope Authorizes Access to
patient/Observation.read Read all observations about the patient in context
patient/Observation.write Add new observations about, such as new blood pressure readings.
user/Observation.read Read a feed of all new lab observations across a patient population.
user/Appointment.write Add new appointments for the user.
system/Patient.read Read all patient records accessible to the given client using its own credentials.

Scopes for Identity Information

The following scopes are defined for requesting identity information:

See the section User Identity for more information on how to utilize the identity information.

Scopes for Launch Information

When servicing a launch request, a SMART application MUST include the scope of “launch” in its list of requested scopes.

For SMART applications performing the SMART Application Launch Flow, the following scopes are defined by this specification:

Scope Requests context
launch/patient Requests the EHR provide context regarding a patient.
launch/encounter Requests the EHR provide context regarding an encounter.

An EHR MAY support additional custom launch scopes. When doing so, the scope name must conform to the syntax defined in appendix A.2..

Scopes for Longevity

SMART on FHIR® provides a mechanism for a client application to request a longevity for the access that is being requested. Without such modifiers, no assumptions can be made about how long access may be granted. A given authorization server SHOULD generate access tokens that have very short lifetimes by default, and provide a refresh token where longer access has been explicitly requested.

To request longevity, a SMART application MAY include one of the two following scopes:

These scopes MUST NOT be used in conjunction with the client credentials flow, as they are not applicable to that use case.

Disambiguation of Scopes Between Competing Protocols

In the event that an authorization request is used in conjunction with that of a protocol that defines a competing scope, a SMART application or authorization server MAY prepend the following prefix to a scope:

http://smarthealthit.org/FHIR/scopes/

Normative example:

http://smarthealthit.org/FHIR/scopes/user/Observation.read

Applications and authorization servers MUST consider the fully-qualified scope names semantically equivalent to the shorthand versions where no conflicts exist with other values. For example, an authorization server MAY choose to return the fully-qualified scopes in the authorized access token response in response to the short-hand versions being used.

NOTE: The openid and fhirUser scopes are defined by the OpenID Connect specification, which does not define a prefix.

User Identity

SMART on FHIR® allows for identity information about the end user to be obtained via an OpenID Connect identity token. SMART applications MAY request such identity information by requesting the scope of openid during its authorization request. Authorization servers MUST provide an id_token as part of the access token response if the SMART application has been authorized to obtain the information.

OpenID Connect Identifier Permanency

The authorization server MUST include a permanent URL for the issuer (iss) value of the token. The URL MUST NOT contain path segments that vary over time, such as version information for the FHIR® or SMART protocol being utilized. The value of the subject (sub) of the id_token must be a permanent identifier for the end user, whose value is stable. SMART applications MUST treat the combination of issuer and subject as the universally unique identifier for the end user.

Non-repudiation of OpenID Connect id_tokens

The authorization server SHALL sign the id_token per the OpenID Connect specification using the RS256 algorithm.

The authorization server SHALL make its public keys available as described in OpenID Connect Discovery, incorporating both an “OpenID Provider Configuration” document and a “JSON Web Key” document describing the public key(s) used to sign tokens.

SMART applications MUST validate the token per the token validation section of OpenID Connect.

fhirUser Resource

In addition to the to requesting access to the user’s OpenID identity, a SMART application MAY request access to the FHIR® resource that represents the user through the addition of the “fhirUser” scope. The authorization server SHALL fulfill such by including a fhirUser claim in the id_token.

An EHR MAY include the URI of the user’s FHIR® resource. This resource may be a Patient, Practitioner, RelatedPerson, or Person resource as described by the FHIR® Specification. SMART applications wishing to retrieve that resource MUST explicitly include the relevant scope(s) when requesting their access tokens.

Discovery

To support automated discovery of OAuth2 endpoints, a SMART on FHIR® EHR publishes a set of OAuth2 endpoint URLs inside its conformance statement on the Conformance.rest.security element.
The following elements are extensions identified by the following URI:

http://FHIR-registry.smarthealthit.org/StructureDefinition/oauth-uris

The content of the extension defines the following urls, each associated with a valueUri:

Non-normative conformance example as JSON:

{
  "resourceType": "Conformance", 
  ...
  "rest": [
    {
      ...
      "security": {
        "extension": [
          {
            "url": "http://FHIR-registry.smarthealthit.org/StructureDefinition/oauth-uris",
            "extension": [
              {
                "url": "token",
                "valueUri": "https://my-server.org/token"
              },
              {
                "url": "authorize",
                "valueUri": "https://my-server.org/authorize"
              },
              {
                "url": "manage",
                "valueUri": "https://my-server.org/manage"
              }
            ]
          }
        ],
        ...

Client Authentication

To mitigate the risk of compromised refresh tokens, SMART applications SHOULD leverage client authentication when storing such refresh tokens outside of the client component of their application (e.g. storing in a central database, in memory on an application server, etc.) This ensures that in the event such refresh tokens are compromised, that the tokens need not be revoked. If the client’s credentials are stolen in addition to the tokens, a client application need only to revoke its previous credentials with EHRs.

Registration

A SMART application that utilizes the Contextless Flow, EHR Launch Flow, or SMART Application Launch Flow MUST supply the following information when registering with an EHR:

Exception Conditions

During the processes of obtaining access tokens and utilizing access tokens, it is possible for exceptions to occur. Such exceptions could be caused by, but are not limited to, the following conditions:

In the majority of cases, the EHR system will have the most information as to the cause of the failure, and will be in the best position to offer assistance to the user and/or individuals whom support a given the SMART application. As such, it is RECOMMENDED that authorization servers and resource servers utilize the “error_uri” parameter as detailed in the following specifications:

SMART applications that receive such information in error responses SHOULD present such links to end users.

It is RECOMMENDED that such links provide actionable instructions for either the end user or for individuals whom are supporting the SMART application. It is RECOMMENDED for SMART applications to provide a mechanism to retry a specific action after an error to assist users in recovering from transient error conditions.

Security Considerations

Appendix

This section provides Augmented Backus-Naur Form (ABNF) syntax descriptions for the elements defined in this specification using the notation of RFC 5234, and additionally utilizes other syntax definitions defined in Appendix A of the OAuth 2.0 Framework.

A.1. Resource Scope Syntax

scope-name          = resource-context "/" resource-type "." modification-rights
resource-context    = ("user" / "patient") 
resource-type       = (Name)
modification-rights = ("read" / "write");

A.2. Launch Scope Syntax

  launch-scope      = "launch/" *( SP scope-token )

A.3. Launch Code Syntax

  launch-code       = 1*VSCHAR

A.4. Launch Issuer Syntax

  launch-issuer     = URI-reference

A.5. Launch Intent Syntax

  launch-intent     = 1*VSCHAR

References