From d1ad4aa01d496d851554325e3b2187f3a7ea3df2 Mon Sep 17 00:00:00 2001 From: bakerdb Date: Mon, 17 Aug 2015 10:57:12 -0700 Subject: [PATCH 1/4] Scope limit to the minimum necessary The grants, scope, and period of time requested by the client should be guided by the minimum necessary rule, per HIPAA and basic security principle. --- specification/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/index.md b/specification/index.md index b8405c9..f160340 100644 --- a/specification/index.md +++ b/specification/index.md @@ -231,8 +231,9 @@ the SMART application is already known. Examples of such scenarios include: ###2.1.2 Authorization Request### SMART applications __SHALL__ utilize an [authorization code grant][4] to request authorization to FHIR -resources. A SMART application __SHOULD__ request scopes needed to access the resource (per the [scopes](#3) -section) for maximum interoperability. The application __MAY__ choose to omit the redirect URI, as SMART +resources. A SMART application __SHOULD__ limit the grants, scope (per the [scopes](#3) +section), and period of time requested to the +minimum necessary. The application __MAY__ choose to omit the redirect URI, as SMART registration is limited to a single redirect URI for SMART applications. In addition, SMART applications __MUST__ send the "state" parameter, as detailed in the From 3328cb6e5a87f6d9d91dd6b1673f2815f5a9e97c Mon Sep 17 00:00:00 2001 From: bakerdb Date: Mon, 17 Aug 2015 14:38:28 -0700 Subject: [PATCH 2/4] Parameters in authorization request Added required and optional parameters included in the authorization request. Content that was here was inconsistent with the Argonaut SMART on FHIR profile. Via a separate pull request, I have also requested that the content regarding use of the OS's native browser also should be removed from this section. --- specification/index.md | 83 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 77 insertions(+), 6 deletions(-) diff --git a/specification/index.md b/specification/index.md index f160340..01ae4d1 100644 --- a/specification/index.md +++ b/specification/index.md @@ -231,14 +231,85 @@ the SMART application is already known. Examples of such scenarios include: ###2.1.2 Authorization Request### SMART applications __SHALL__ utilize an [authorization code grant][4] to request authorization to FHIR -resources. A SMART application __SHOULD__ limit the grants, scope (per the [scopes](#3) -section), and period of time requested to the -minimum necessary. The application __MAY__ choose to omit the redirect URI, as SMART -registration is limited to a single redirect URI for SMART applications. - -In addition, SMART applications __MUST__ send the "state" parameter, as detailed in the +resources. The request for authorization will include the following parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameters
response_typerequiredFixed value: code.
client_idrequiredThe client's identifier.
redirect_urirequiredMust match one of the client's pre-registered redirect URIs.
launchoptionalWhen using the EHR launchflow, this must match the launch value received from the EHR.
scoperequired + +Must describe the access that the app needs, including clinical data scopes like +patient/*.read, openid and profile (if app +needs authenticated patient identity) and either: + +
    +
  • a launch value indicating that the app wants to receive already-established launch context details from the EHR
    • +
  • a set of launch context requirements in the form launch/patient, which asks the EHR to establish context on your behalf. +
+ +See SMART on FHIR Access +Scopes details. + +
staterequired + +An opaque value used by the client to maintain state between the request and +callback. The authorization server includes this value when redirecting the +user-agent back to the client. The parameter MUST be used for preventing +cross-site request forgery or session fixation attacks, as detailed in the [OAuth 2.0 Security Considerations][5]. +
audrequired + +URL of the EHR resource server from which the app wishes to retrieve FHIR data. +This parameter prevents leaking a genuine bearer token to a counterfeit +resource server. (Note: in the case of an EHR launch +flow, this aud value is the same as the launch's iss value.) + +
+ + +A SMART application __MUST__ limit the grants, scope (per the [scopes](#3) +section), and period of time requested to the +minimum necessary. + SMART applications that are written natively for a platform __SHOULD__ utilize the operating system's default browser when performing the authorization request such that the authorization server may comply with any security controls that have been imparted upon it. Such controls may include: From 2496f38ad5466536963d4b52d7b59367e2d1916f Mon Sep 17 00:00:00 2001 From: bakerdb Date: Mon, 17 Aug 2015 14:43:11 -0700 Subject: [PATCH 3/4] Added content re entropy --- specification/index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/specification/index.md b/specification/index.md index 01ae4d1..a37bc9e 100644 --- a/specification/index.md +++ b/specification/index.md @@ -306,9 +306,16 @@ flow, this aud value is the same as the launch's iss v -A SMART application __MUST__ limit the grants, scope (per the [scopes](#3) +A SMART application __SHOULD__ limit the grants, scope (per the [scopes](#3) section), and period of time requested to the -minimum necessary. +minimum necessary. + +The application MUST use an unpredictable value for the state parameter +with at least 128 bits of entropy. The application MUST validate the value +of the state parameter upon return to the redirect URL and MUST ensure +that the state value is securely tied to the user’s current session +(e.g., by relating the state value to a session identifier issued +by the application). SMART applications that are written natively for a platform __SHOULD__ utilize the operating system's default browser when performing the authorization request such that the authorization server may comply with any security controls that From 5d5e51d9e1403268175c4c76790e651076f71a9f Mon Sep 17 00:00:00 2001 From: bakerdb Date: Mon, 17 Aug 2015 14:47:03 -0700 Subject: [PATCH 4/4] Update index.md --- specification/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/index.md b/specification/index.md index a37bc9e..ef781d4 100644 --- a/specification/index.md +++ b/specification/index.md @@ -317,6 +317,12 @@ that the state value is securely tied to the user’s current session (e.g., by relating the state value to a session identifier issued by the application). +If the app needs to authenticate the identity of the end-user, it should +include two OpenID Connect scopes: `openid` and `profile`. When these scopes +are requested, and the request is granted, the app will receive an id_token +along with the access token. For full details, see [SMART launch context +parameters](./scopes-and-launch-context). + SMART applications that are written natively for a platform __SHOULD__ utilize the operating system's default browser when performing the authorization request such that the authorization server may comply with any security controls that have been imparted upon it. Such controls may include: