On this page:

11.18SMART: 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.

Login

  • 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.

Approval

11.18.1Auto-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.

11.18.2Approval 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:

Scope Approval

11.18.3Customizing 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

11.18.4Custom 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.

Example

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.

Approval

11.18.5Revoking Security Scopes

 

A user can revoke security scopes by navigating to '/oauth/revoke' on the Smart Auth Endpoint. On the default configuration this is http://www.example.com:9200/oauth/revoke. 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.