16.4.1SMART on FHIR: Smile CDR Support

 

This page describes support for SMART on FHIR Security within Smile CDR. Note that this page uses terms described on the SMART on FHIR: Introduction page. If you haven't read that already, you should start there.

There are several modules that can be used in different ways in order to create a complete SMART on FHIR compliant architecture.

16.4.2Models for Using External OIDC Servers

 

If you have a third-party OIDC provider, there are two ways you can integrate Smile CDR with the OIDC provider:

Direct Integration Federated OAuth2/OIDC Login
Flow Description Tokens are issued by a third-party OpenID Connect Server and passed to an Application. The application passes the token to Smile CDR when making service requests, and Smile CDR validates it in order to authenticate requests. Tokens are issued by a third-party OpenID Connect Server and passed directly to Smile CDR. Smile CDR inspects the token, and if successful Smile CDR issues a new token which is then passed to the Application. The application passes the token to Smile CDR when making service requests, and Smile CDR validates it in order to authenticate requests.
Requirements for Third-Party OIDC Server The third-party OpenID Connect server must fully support the SMART on FHIR extensions to the OIDC Spec, including the ability to approve SMART Scopes, and the ability to enrich tokens with launch context details. The third-party OpenID Connect server must support the base OIDC specification only.
Client Definitions for SMART Applications Managed by third-party Authorization Server Managed by Smile CDR

16.4.3Supported Scopes

 

The following table lists the scopes that are supported by Smile CDR.

Note: Client definitions may include scopes other than the scopes listed here, and clients may approve them. However, any scopes that are not listed here will be transparent to Smile CDR. If you use custom scopes, you may need to supply descriptions that will be shown when the user is prompted to approve them by the SMART Outbound Security module. See Custom SMART Scope Names for an example of how to do this.

https://hl7.org/fhir/uv/bulkdata/authorization/index.html#scopes
Scope Description
User Identity openid fhirUser This pair of scopes permits the client to request details about the logged in user. They enable the OpenID Connect id_token claim. When the fhirUser scope is used, the ID Token will contain a claim (also called fhirUser) that contains a link to the FHIR Resource accociated with the logged in user. See SMART User Profile for more information.
User Identity openid profile This pair of scopes permits the client to request details about the logged in user. They enable the OpenID Connect id_token claim. Using the profile scope is an alternative to the fhirUser scope discussed above, and is supported by Smile CDR, but it is deprecated in the SMART App Launch specification.
Refresh Tokens online_access This scope permits that the client be issued a Refresh Token upon authentication, and permits the user to exchange the Refresh Token for an Access Token. This scope has no effect for clients that do not support the refresh_token grant type.
offline_access This scope permits that the client be issued a Refresh Token upon authentication, and permits the user to exchange the Refresh Token for an Access Token. This scope has no effect for clients that do not support the refresh_token grant type.
SMART on FHIR Launch
See Launch Context Scopes for a description of what these scopes do.
launch/patient Standalone Patient Launch Context: Request that the server provide a contextual Patient resource identifier as a part of the claims returned to the client during the authorization flow. If this scope is requested and approved by the user, the Patient launch context will be taken from the UserSessionDetails.launchResourceIds array if any entries exist with a type of patient. If none are found, UserSessionDetails.defaultLaunchContexts will also be searched for any entries with a type of patient.
launch/encounter Standalone Encounter Launch Context: Request that the server provide a contextual Encounter resource identifier as a part of the claims returned to the client during the authorization flow. If this scope is requested and approved by the user, the Patient launch context will be taken from the UserSessionDetails.launchResourceIds array if any entries exist with a type of encounter. If none are found, UserSessionDetails.defaultLaunchContexts will also be searched for any entries with a type of encounter.
launch/location Standalone Location Launch Context: Request that the server provide a contextual Location resource identifier as a part of the claims returned to the client during the authorization flow. If this scope is requested and approved by the user, the Patient launch context will be taken from the UserSessionDetails.launchResourceIds array if any entries exist with a type of location. If none are found, UserSessionDetails.defaultLaunchContexts will also be searched for any entries with a type of location.
launch EHR Launch Context: Request that the server provide any relevant launch context information available. If this scope is requested and approved by the user, the Patient launch context will be taken from the UserSessionDetails.launchResourceIds array. If none are found, UserSessionDetails.defaultLaunchContexts will also be searched for any entries.
SMART on FHIR Data Access
This section lists the SMART on FHIR scopes natively supported by Smile CDR. See Scope Permission Model for a description of how these scopes are actually applied to a user session.
patient/*.read This scope permits the client to read (read/search/history) all data for all patients on the server. In other words, all data in any Patient compartment.
patient/*.write This scope permits the client to write (create/update) all data for all patients on the server. In other words, all data in any Patient compartment.
patient/[ResourceType].read This scope permits the client to read (read/search/history) all data for the given resource type for all patients on the server. Note that [ResourceType] must be a valid FHIR Resource type (e.g. Observation).

Clients that have been configured to support wildcard scopes (e.g. Patient/*.read) are also permitted to request this scope without needing to have it declared explicitly in the client definition.
patient/[ResourceType].write This scope permits the client to write (create/update) all data for the given resource type for all patients on the server. Note that [ResourceType] must be a valid FHIR Resource type (e.g. Observation).

Clients that have been configured to support wildcard scopes (e.g. Patient/*.read) are also permitted to request this scope without needing to have it declared explicitly in the client definition.
Scope Restriction via Query Filters Smile provides limited support for the new features of SMART v2. Scopes may include a FHIR query expression to limit their application to resources that match the expression. For example: `patient/Observation.read?category=laboratory` will only provide access to Observations with category code of `laboratory`. Smile does not currently support the new `cruds` syntax for access permissions. See SMART 2.0 Scopes for configuration details.
user/*.read user/*.write These scopes operate like the patient/* scopes above. See User-level scopes
system/*.read system/*.write The system/* scopes are part of the of SMART Backend Services extension. These scopes operate like the patient/* scopes above.
Smile CDR FHIR Extensions
The SMART on FHIR scope specification covers basic clinical read/write scenarios well, but leaves a number of other part of the FHIR specification without any relevant scopes for authorizing use. This section describes Smile CDR specific scopes that can be used to add additional FHIR capabilities to applications.
cdr_fhir_delete

This scope permits the user to perform FHIR delete operations.

Associated permissions:
FHIR_ALL_DELETE
FHIR_DELETE_ALL_IN_COMPARTMENT
FHIR_DELETE_CASCADE_ALLOWED
FHIR_DELETE_TYPE_IN_COMPARTMENT
FHIR_DELETE_ALL_OF_TYPE

cdr_fhir_expunge

This scope permits the user to perform FHIR expunge operations.

Associated permissions:
FHIR_EXPUNGE_DELETED
FHIR_EXPUNGE_PREVIOUS_VERSIONS
FHIR_EXPUNGE_EVERYTHING

cdr_fhir_validate

This scope permits the user to perform FHIR $validate operations.

Associated permissions:
FHIR_MANUAL_VALIDATION

cdr_mdm

This scope causes searches performed by the user to automatically apply MDM expansion to resources in the Patient compartment without needing to provide the :mdm qualifier in the query.

Associated permissions:
FHIR_AUTO_MDM

Misc. Permissions cdr_all_user_authorities This is a special scope that grants the session all permissions that are granted to the authorizing user. Note that this scope supercedes all other data access scopes. This is useful if you wish to have clients/applications authorizing using SMART on FHIR that need to access administrative functions of Smile CDR.

16.4.4Online / Offline Access

 

Note that at present the online_access and offline_access scopes have identical functionality; this is because a standalone CDR and an EHR do not share the same concept of a user session. In future, functionality may be added that allows a more complete online_access session concept.