HL7 SMART App Launch Active User Presence Extension
Introduction
The HL7 SMART App Launch specification defines the scope1 of online_access
, enabling an application to obtain refresh tokens2 that “will be usable for as long as the end-user remains online”. In certain use cases, conflicts between user experience and security can arise when the user’s primary interaction with the electronic health record is through a SMART on FHIR application. In these scenarios, the electronic health record may have awareness that an application is continuing to utilize FHIR resources and refresh tokens, but there is no guarantee that such activity constitutes “active user presence”. Best practices for session management, such as those prescribed by NIST 800-63B2, describe requirements for users to be re-authenticated after “inactivity”. When users are not directly interacting with an application that is part of the electronic health record, a mechanism by which a SMART on FHIR application can communicate active user presence is desirable to prevent the user from experiencing unnecessary re-authentication events.
To address this concern, this extension provides a mechanism by which a SMART on FHIR authorization server may declare that a refresh token is subject to inactivity constraints as part of its own token responses. Through this extension a SMART on FHIR application may correspondingly include a parameter in token refresh requests that conveys how long ago the application last detected active user presence.
Protocol Flow
+-------------------+ | Authz Server | +--------+ | +---------------+ | | |--(A)-- Access Token Request ---->| | | | | | | | | | | | | | | | |<-(B)-- Access, Refresh Token ----| | | | | + "active_ttl" | | Token | | | Client | | | Endpoint | | | | | | | | | |--(C)-- Refresh Request --------->| | | | | + "active_at" | | | | | | | | | | | |<-(D)------ Access Token ---------| | | +--------+ + "active_ttl" | +---------------+ | +-------------------+
Figure 1: Abstract Protocol Flow
This specification adds additional parameters to the SMART on FHIR Access Token Response, Refresh Request, and Refresh Response shown in abstract form in Figure 1.
A. The client performs an Access Token Request using an established authorization code that was established with an online_access
scope.
B. The Token Endpoint responds with an access token and refresh token as usual, but additionally includes the parameter active_ttl
. This value signifies the quantity of seconds (time-to-live) remaining before user is no longer considered active, which will automatically invalidate the refresh token without further activity..
C. Prior to the invalidation time specified by active_ttl
, the client application performs a Refresh Request as usual but includes a parameter active_at
that specifies how many seconds in the past that the client application last detected active user presence.
D. The Token Endpoint responds as usual but includes another active_ttl
value, again signifying the new quantity of seconds remaining before the refresh token will be automatically invalidated without active user presence.
This specification uses time vectors in seconds rather than absolute date/time objects as to avoid issues with clock skew between the authorization server and the application.
Notational Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in “Key words for use in RFCs to Indicate Requirement Levels”4. If these words are used without being spelled in uppercase, then they are to be interpreted with their natural language meanings.
This specification uses the Augmented Backus-Naur Form (ABNF) notation of RFC 52345.
Terminology
Active User Presence: Any event that can be construed as a human interaction with a computing device. This includes, but is not limited to mouse, keyboard, scroll, click, tap, and gesture interactions.
Protocol
Authorization Server Declares Active User Presence Requirement
When issuing token responses containing refresh tokens scoped for online_access
, the SMART on FHIR authorization server returns the number of seconds after which the session will be considered inactive, active_ttl
, in the following manner:
active_ttl = 1*DIGIT
The inclusion of this attribute in a token response from an authorization server signals to the SMART application that the authorization server supports / has implemented this specification, and that it will accept additional parameters to signal user presence as part of the token refresh process.
If no active user presence is detected by an actor participating with the authorization server (the electronic health record or a SMART on FHIR application) after this number of seconds has passed, the authorization server SHOULD invalidate any refresh tokens associated with the user session.
Application Performs Token Refresh
When an application sends a Refresh Request, it MAY include the parameter active_at
to specify the number of seconds that have passed since active user presence was detected, in the following manner:
active_at = 1*DIGIT
If the refresh token is still valid and the “active_at” parameter is present, the authorization server calculates the instance of last activity in the SMART app by subtracting active_at
from the current date/time:
current date/time - active_at = instance of user's last activity in the SMART app
If the instance of user’s last activity in the SMART app is more recent than the instance of the user’s last activity known to the authorization server, then the authorization server SHALL update its record of the instance of the user’s last activity for the session and use that in its calculation of an updated active_ttl
value to return in the response to the Refresh Request.
Negative active_at
values MUST be rejected, treating the request as if the active_at
parameter were not included.
If the refresh token is invalid, either due to lapse of user activity or other invalidation, the server responds per section 5.2. The application MAY initiate a new authorization grant request, if appropriate. An authorization server MAY allow other means (outside of the scope of this specification) to re-enable the refresh token. As such, applications SHOULD provide a retry option to end users.
References
1 SMART App Launch: Scopes and Launch Context - Scopes for requesting a refresh token
3 The OAuth 2.0 Authorization Framework - Refreshing an Access Token