Welcome to Smile CDR

Getting Started

Installation

Tutorial and Tour

The FHIR Standard

FHIR Storage

FHIR Storage (Relational)

FHIR Storage (MongoDB)

Validation and Conformance

Terminology

Subscription

Interceptors

Channel Import

Channel Import Overview 13.0

Realtime Export

Security

SMART on FHIR

appSphere

FHIR Gateway

FHIR Hybrid Providers

LiveBundle

CDS Hooks

CDS Hooks 21.0

Master Data Management

Quality Improvement

IG Support

International Patient Summary (IPS) 24.0

EasyShare

Clustering

Logging

HL7 v2.x Support

CDA Exchange Module

CDA Exchange+ Module

System to System Data Exchange

Bulk Operations

Additional Features

Monitoring

Product Administration

JSON Admin Endpoints

HFQL: Direct SQL Access

Product Configuration

Java Execution Environment

JavaScript Execution Environment

Database Administration

Localization

Smile CDR CLI (smileutil)

Apache Camel Integration

Modules

Configuration Categories

Product Reference

Enumerated Types 50.0

Amazon HealthLake Outbound REST Connector

Appendix

16.9 SMART: Federated OAuth2/OIDC Login 16.11 SMART Inbound Security Module

16.10.1SMART: Application Approval / Consent

When using the SMART Outbound Security module to perform a SMART Application login, the user is typically presented with two screens during the authentication flow.

These screens are described below. The screenshots show these screens using their out-of-the-box configuration, but these screens can be skinned for complete customization.

Step 1: Login Page

This page asks the user for credentials.

Step 2: Approval Page

The second page is called the Approval Page, but is also sometimes referred to by implementers as the App Consent Page.

This page asks the user to confirm that they wish to sign in to the application, and requests confirmation of the OAuth2/SMART scopes being requested by the application.

16.10.2Approval Overview

16.10.3Auto-Approve / Auto-Grant Scopes

In the OIDC Client Definition, the Scopes property defines the scopes that an application is allowed to request. Any scopes that are requested by an application will be ignored unless they appear in this list.

By default, when an application requests a given scope, the user will be presented with a choice to approve or reject this scope. This step may or may not make sense depending on the application and its context of use. It is important to remember that requested scopes represent a request by the application to gain the ability to access or modify data on the user's behalf. They do not represent actions the user themself is allowed to perform (this concept is represented by Smile CDR permissions)

For example in the case of a Provider Application being deployed by a hospital to its clinicians, it may not make sense to require user approval for scopes since the data belongs to the organization supplying the application.

On the other hand, in the case of a Patient Application being provisioned for public consumption, explicit approval can be helpful in order to allow users to understand what data and actions are being requested by the application, and to allow these users to make informed choices about using the application.

If you wish to suppress the explicit approval of scopes, the following options can be used:

Auto-Approve Scope: If a scope is listed in the OIDC Client Definition as an auto-approve scope, it will be automatically granted (without explicit user approval) as long as the application requests it.
Auto-Grant Scope: If a scope is listed in the OIDC Client Definition as an auto-grant scope, it will be automatically granted (without explicit user approval) even if the application does not request it.

16.10.4Approval Flow

When a client requests authorization using an Interactive Flow, the user may or may not be presented with an approval page after they successfully enter their credentials.

The following diagram shows the scope approval steps:

16.10.5Customizing Scope Names

When using SMART on FHIR Applications, an important part of the security model involves allowing applications to request specific scopes.

If these scopes are configured in the OIDC Client Definition as auto-approve/auto-grant scopes, then the user will not be prompted for approval.

Smile CDR ships with default descriptions for SMART scopes, but you may wish to customize these in order to provide meaningful terms that make sense for the user population.

To customize a scope name, a property should be added to the cdr-messages.properties file with the following key: webadmin.view.security_out_smart.scope.[SCOPE].name (where [SCOPE] has been substituted for the actual scope text).

For example the following line in the localization file will rename the patient/*.read scope:

webadmin.view.security_out_smart.scope.patient/*.read.name=View Your Clinical Information

16.10.6Custom Security Scopes

The SMART on FHIR Scope framework provides a common mechanism for allowing applications to request data permissions in a standardized way. While this framework is quite powerful, it can not always express the detailed rules that may be required in order to meet specific project requirements, regulatory rules for a given jurisdiction, etc.

For example, an organization might wish to restrict access to a specific kind of laboratory test, allowing only specific apps to request this data and requiring users to explicitly approve this request.

A common approach for implementing this requirement is to define a custom scope and then require user approval for this scope. The Smile CDR Consent Service can then be used to apply detailed filtering based on the approved scopes.

16.10.6.1Example

For example, suppose you wished to suppress the release of SARS-nCov-2 results unless an application explicitly requests and is approved to access them.

In order to accomplish this, a new scope called observation_view_covid19 is created. The scope text should be chosen such that it does not conflict the names of existing SMART scopes, or of built-in OpenID Connect scopes (openid, profile, email, etc). To define this scope:

Add the scope to the list of scopes in the OIDC Client Definition for the application. Note that custom scopes do not need to be pre-defined elsewhere (e.g. in the module configuration) in order to be used. If a scope is listed in the client defnition, it can be requested and approved.
Optionally, you may wish to add the scope as an Auto-Approve or Auto-Grant scope (see above).
If you are requiring explicit user approval for this scope, you should add a name for the scope to the localization file.

webadmin.view.security_out_smart.scope.observation_view_covid19.name=Access your COVID-19 Test Results

A Consent Service script can now be created which permits or blocks access to these test results based on whether the scope is approved for a given user session. Refer to Example: Scope-Based Consent Script to see an example of how this script can be implemented.

The following screenshot shows an example of how the approval page will appear to an authenticating user, assuming the new custom scope has not been marked as Auto-Approve or Auto-Grant. Note of course that this page shows Smile CDR branding by default, but as with all pages in the SMART Outbound Security module, it can be completely skinned.

16.10.7Revocation Page

A user can revoke client access for a specific client (or all clients) that they have previously approved by navigating to '/session/management' on the Smart Auth Endpoint. On the default configuration this is http://www.example.com:9200/session/management.

After logging in, the user is presented with a list of applications with a "Revoke" button beside each. When the user clicks on the Revoke button for a specific application, all scope approvals are removed for that application. If the user needs to add those scopes back again in the future, they will need to go through the approval process again for that application.

A client will be shown as active (and therefore being eligible to be revoked) if any of the following holds true:

The user has previously approved scopes for this client, and the client definition includes the Remember Approved Scopes setting.
There is at least one Access Token that has been issued for the user for this client that is active and not yet expired.
There is at least one Refresh Token that has been issued for the user for this client that is active and not yet expired.

Revoking the client will forget any previously remembered scope approvals, and deactivate any active Access and Refresh tokens for the client. It will also revoke any prior agreements to Terms of Service for the user.