HealtheData1 USCDI4 Sandbox - Local Development build (v0.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

SMART on FHIR Obligations and Capabilities

SMART App Launch Implementation Guide Release 2.0.0 describes a set of foundational patterns based on OAuth 2.0 for client applications to authorize, authenticate, and integrate with FHIR-based data systems. This page documents the SMART on FHIR obligations and capabilities for US Core Servers supporting User-Facing Applications and Backend Services.

Capability Sets for US Core Servers Supporting User-Facing Applications adn Backend Services

To promote interoperability, SMART on FHIR defines a set of core capabilities. An individual SMART server will publish a granular list of its capabilities and a given set of these capabilities is combined to support a specific use, a Capability Set. See SMART App Launch’s FHIR OAuth authorization Endpoints and Capabilities for more details. Servers MAY support the other SMART on FHIR Capability Sets and capabilities than those listed below.

Capabilities for Implementations supporting User-Facing Applications

At least one of the following SMART on FHIR Capability Sets SHOULD be supported for US Core Servers that support User-Facing Applications. For certified systems both SHALL be supported:

• Patient Access for Standalone Apps
• Clinician Access for EHR Launch

Capabilities for Implementations supporting Backend Services

Implementations supporting Backend Services – for example, to meet US EHR certification requirements - SHALL include support for the client-confidential-asymmetric capability and system/scopes.

US Core Servers SHALL Support Token Introspection

​US Core Server SHALL support token introspection defined by the SMART App Launch Guide. For more details and additional consideration see SMART App Launch’s Token Introspection.

SMART Scopes

SMART’s scopes defined in Version 2.0.0 of the [SMART App Launch] implementation guide allow a access permissions to be delegated to a client application. The US Core API requires servers to support [resource level scopes] and [granular scopes] allowing access to specific data about a single patient. US Core’s required scopes (SHALL) are based on community-based consensus that the scope meets a system requirement, clinical need, or federal regulation. Similarly, US Core’s recommended scopes (SHOULD) rely on community-based consensus that the scope meets a system requirement or clinical need as a best practice.

The US Core required scopes listed below are named in the HTA-1 final rule, which requires support for Condition and Observation category scopes, and the recommended granular scope listed below is of particular interest to patients and health systems. Implementations meeting US EHR certification requirements need to support all US Core’s required scopes. Other systems only need to support scopes for the US Core APIs they support.

Each US Core Profile page includes a “Quick Start” section summarizing the supported search transactions and scopes for each profile. Servers MAY support other scopes in addition to those listed below and in the the Quick Start sections. US Core clients should follow the [principle of least privilege] and access only the necessary resources. In other words, if a client needs only vital sign observations, it should request access only to Observations with a category of “vital-signs”.

Scopes Format

SMART App Launch Version 2.0.0 introduced a scope syntax of: <patient|user|system> / <fhir-resource>. <c | r | u | d |s> [?param=value]

For example, to limit read and search access to a specific patient’s laboratory observations but not other observations, the server grants the following patient-specific scope:

patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory.

This example uses a patient/ prefix, but implementers may support system/ and user/.

US Core Scopes

The table below summarizes the US Core scope requirements (SHALL) and best practice recommendations (SHOULD) for resource-level and granular scopes. This same information can be found in each US Core Profile page’s “Quick Start” section.

For “User-Facing Applications”, a system’s support for patient-level (patient) or user-level (user) scopes depends on its published list of SMART on FHIR capabilities (see the capability sets above). For example, if a server lists permission-patient and permission-user in its capabilities, it SHALL support both patient-level and user-level required scopes, and SHOULD support both patient-level and user-level recommended best-practice scopes.

For “Backend-Services”, System-level scopes (system) are used to describe data that a client system is directly authorized to access. Systems that support system-level (system) scopes, SHALL support the required US Core scopes and SHOULD support the recommended US Core scopes.

The Following Resource Level Scopes SHALL Be Supported

The Following Resource Level Scopes MAY Be Supported

The Following Granular Scopes SHALL Be Supported

The Following Granular Scopes SHOULD Be Supported

Servers SHALL support the following metadata in their /.well-known/smart-configuration

In addition to the capabilities defined in the server’s CapabilityStatement, servers SHALL document their SMART capabilities in a using a Well-Known Uniform Resource Identifiers (URIs) JSON file.

Required SMART App Launch Metadata

The following JSON file metadata are required by the SMART App Launch guide:

• issuer (conditional)
• jwks_uri (conditional)
• authorization_endpoint
• grant_types_supported
• token_endpoint
• capabilities
• code_challenge_methods_supported

Additional US Core Requirements

These additional SMART App Launch metadata are required by US Core:

• scopes_supported : Array of scopes a client may request.

  • The server SHALL support all scopes listed in the table above for the US Core Profiles they support; additional scopes MAY be supported (so clients should not consider this array an exhaustive list).

  • Servers MAY limit clients’ scopes to those configured at registration time. Servers SHALL allow users to select a subset of the requested scopes at the approval time. The app SHOULD inspect the returned scopes and accommodate the differences from the scopes it requested and registered.

• introspection_endpoint: URL to a server’s introspection endpoint that can be used to validate a token.
  • Servers SHALL document this endpoint in the file

Example .well-known/smart-configuration File

This example .well-known/smart-configuration file shows all the required and recommended metadata listed in SMART App Launch for a certified systems supporting User-Facing Applications and Backend Services. Note that the server lists all the required and recommended US Core scopes for both patient/, user/, and system/ in the scopes_supported metedata array. See the [SMART App Launch] Implementation Guide for more examples and details.

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",
  "scopes_supported": [
    "openid",
    "profile",
    "launch",
    "launch/patient",
    "offline_access",
    "patient/AllergyIntolerance.rs",
    "user/AllergyIntolerance.rs",
    "system/AllergyIntolerance.rs",
    "patient/CarePlan.rs",
    "user/CarePlan.rs",
    "system/CarePlan.rs",
    "patient/CareTeam.rs",
    "user/CareTeam.rs",
    "system/CareTeam.rs",
    "patient/Condition.rs",
    "user/Condition.rs",
    "system/Condition.rs",
    "patient/Coverage.rs",
    "user/Coverage.rs",
    "system/Coverage.rs",
    "patient/Device.rs",
    "user/Device.rs",
    "system/Device.rs",
    "patient/DiagnosticReport.rs",
    "user/DiagnosticReport.rs",
    "system/DiagnosticReport.rs",
    "patient/DocumentReference.rs",
    "user/DocumentReference.rs",
    "system/DocumentReference.rs",
    "patient/Encounter.rs",
    "user/Encounter.rs",
    "system/Encounter.rs",
    "patient/Goal.rs",
    "user/Goal.rs",
    "system/Goal.rs",
    "patient/Immunization.rs",
    "user/Immunization.rs",
    "system/Immunization.rs",
    "patient/MedicationDispense.rs",
    "user/MedicationDispense.rs",
    "system/MedicationDispense.rs",
    "patient/MedicationRequest.rs",
    "user/MedicationRequest.rs",
    "system/MedicationRequest.rs",
    "patient/Observation.rs",
    "user/Observation.rs",
    "system/Observation.rs",
    "patient/Organization.rs",
    "user/Organization.rs",
    "system/Organization.rs",
    "patient/Patient.rs",
    "user/Patient.rs",
    "system/Patient.rs",
    "patient/Practitioner.rs",
    "user/Practitioner.rs",
    "system/Practitioner.rs",
    "patient/PractitionerRole.rs",
    "user/PractitionerRole.rs",
    "system/PractitionerRole.rs",
    "patient/Procedure.rs",
    "user/Procedure.rs",
    "system/Procedure.rs",
    "patient/Provenance.rs",
    "user/Provenance.rs",
    "system/Provenance.rs",
    "patient/QuestionnaireResponse.rs",
    "user/QuestionnaireResponse.rs",
    "system/QuestionnaireResponse.rs",
    "patient/RelatedPerson.rs",
    "user/RelatedPerson.rs",
    "system/RelatedPerson.rs",
    "patient/ServiceRequest.rs",
    "user/ServiceRequest.rs",
    "system/ServiceRequest.rs",
    "patient/Specimen.rs",
    "user/Specimen.rs",
    "system/Specimen.rs",
    "patient/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern",
    "user/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern",
    "system/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern",
    "patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis",
    "user/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis",
    "system/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis",
    "patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "user/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "system/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "patient/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "user/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "system/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "user/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "system/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "patient/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "user/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "system/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs"
],
  "response_types_supported": ["code"],
  "management_endpoint": "https://ehr.example.com/user/manage",
  "introspection_endpoint": "https://ehr.example.com/user/introspect",
  "revocation_endpoint": "https://ehr.example.com/user/revoke",
  "code_challenge_methods_supported": ["S256"],
  "capabilities": [
    "launch-ehr",
    "permission-patient",
    "permission-user",
    "permission-v2",
    "client-public",
    "client-confidential-symmetric",
    "client-confidential-asymmetric",
    "context-ehr-patient",
    "sso-openid-connect"
  ]
}