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.
This page asks the user for credentials.
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.
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.
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:
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
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
webadmin.view.security_out_smart.scope.patient/*.read.name=View Your Clinical Information
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 orgamization 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.
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
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.