25.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.
25.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 using SMART Inbound Security module
- Federated Integration using SMART Outbound Security module in Federated OAuth2/OIDC Login mode
| 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 |
25.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.
| 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.
|
|
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.
|
|
|
SMART on FHIR Data Access 2.0 SMART 2.0 defines new syntax for permissions, using `c`, `r`, `u`, `d`, and `s`. |
patient/*.c |
Create - this scope permits the client to create (POST) data on the server. |
patient/*.r
|
Read - this scope permits the client to read (GET - read, vread, history) data on the server. | |
patient/*.u
|
Update - This scope permits the client to update (PUT) data on the server. | |
patient/*.d
|
Delete - This scope permits the client to delete (DELETE) data on the server. | |
patient/*.s
|
Search - this scope permits the client to search data on the server. | |
patient/Observation.rs?category=laboratory |
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.rs?category=laboratory` will only provide access to Observations with category code of `laboratory`. | |
|
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: |
cdr_fhir_expunge |
This scope permits the user to perform FHIR expunge operations.
Associated permissions: |
|
cdr_fhir_validate |
This scope permits the user to perform FHIR $validate operations.
Associated permissions: |
|
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
Associated permissions: |
|
| 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. |
25.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.