Conformance and misc

input/fsh/smart-extensions.fsh

@@ -2,7 +2,11 @@ Extension: OauthUris
 Id: oauth-uris
 Title: "SMART on FHIR Oauth URIs"
 
-Description: "Declares support for automated dicovery of OAuth2 endpoints, if a
+Description: "DEPRECATION NOTICE: These discovery extensions have been
+deprecated in favor of SMART capability discovery via
+.well-known/smart-configuration.
+
+Declares support for automated dicovery of OAuth2 endpoints, if a
 server supports SMART on FHIR authorization for access. Any time a client sees
 this extension, it must be prepared to authorize using SMART’s OAuth2-based
 protocol."

input/pages/best-practices.md

@@ -7,10 +7,38 @@ The responsibility of supporting transparent consent falls on both the authoriza
 *Client Application Considerations*
 * In a complex authorization scenario involving user consent, the complexity of the authorization request presented to the user should be considered and balanced against the concept of least privilege. Make effective use of both wildcard and SMART 2.0 fine grained resource scopes to reduce the number and complexity of scopes requested. The goal is to request an appropriate level of access in a transparent manner that the user fully understands and agrees with.
 
-
 *Authorization Server Considerations*
 * For each requested scope- present the user with both a short and long description of the access requested. The long description may be available in a pop-up window or some similar display method. These descriptions should be in plain language, localized to the language set in the user's browser.
 * Consider publishing consent design documentation for client developers- including user interface screenshots and full scope description metadata.  This will provide valuable transparency to client developers as they make decisions on what access to request at authorization time.
 * Avoid industry jargon when describing a given scope to the user. For example, an average patient may not know what is meant if a client application is requesting for access to their "Encounters".
 * If using the experimental query-based scopes, consider how the query will be represented in plain language. If the query cannot easily be explained in a single sentence, adjustment of the requested scope should be considered or proper documentation provided to educate the intended user population.
 
+### App and Server developers should consider trade-offs associated with confidential vs public app architectures
+
+1. Persistent access is important for providing a seamless consumer experience, and Refresh Tokens are the mechanism SMART App Launch defines for enabling persistent access. If an app is ineligible for refresh tokens, the developer is likely to seek other means of achieving this (e.g., saving a user's password and simulating login; or moving to a cloud-based architecture even though there's no use case for managing data off-device).
+
+1. Client architectures where data pass through or are stored in a secure backend server (e.g., many confidential clients) can offer more secure {refresh token :: client} binding, but are open to certain attacks that purely-on-device apps are not subject to (e.g., cloud server becomes compromised and tokens/secrets leak). A breach in this context can be widespread, across many users.
+
+1. Client architectures where data are managed exclusively on end-user devices (e.g., many public clients including most native apps today, where an app is only registered once with a given EHR) are open to certain attacks that confidential clients can avoid (e.g., a malicious app on your device might steal tokens from a valid app, or might impersonate a valid app). A breach in this context is more likely to be isolated to a given user or device.
+
+The choice of app architecture should be based based on context. Apps that already need to manage data in the cloud should consider a confidential client architecture; apps that don't should consider a purely-on-device architecture. But this decision only works if refresh tokens are available in either case; otherwise, app developers will switch architectures just to be able to maintain persistent access, even if the overall security posture is diminished.
+
+## Best Practices
+
+This page reflects best practices established at the time of publication.  For up-to-date community discussion, see [SMART on FHIR Best Practices on the HL7 Confluence Site](https://confluence.hl7.org/display/FHIRI/SMART+on+FHIR+Best+Practices)
+
+### Best practices for server developers include
+
+* Remind users which apps have offline access (keeping in mind that too many reminders lead to alert fatigue)
+* Mitigate threats of compromised refreshed tokens
+* Expire an app's authorization if a refresh token is used more than once (see OAuth 2.1 [section 6.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-02#section-6.1))
+* Consider offering clients a way to bind refresh tokens to asymmetric secrets managed in hardware
+* E.g., per-device dynamic client registration (see ongoing work on [UDAP specifications](https://www.udap.org/))
+* E.g., techniques like the [draft DPOP specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-03)
+
+### Best practices for app developers include
+
+* Ensure that refresh tokens are never used more than once
+* Take advantage of techniques to bind refresh tokens to asymmetric secrets managed in hardware, when available (see above)
+* If an app only needs to connect to EHR when the user is present, maintain secrets with best-available protection (e.g., biometric unlock)
+* Publicly document any code of conduct that an app adheres to (e.g., [CARIN Alliance code of conduct](https://www.carinalliance.com/our-work/trust-framework-and-code-of-conduct/))

input/pages/conformance.md

@@ -4,7 +4,7 @@ may implement a subset of these.  The methods of declaring a server's SMART auth
 
 ### SMART on FHIR OAuth authorization Endpoints and Capabilities
 
-The server SHALL convey the FHIR OAuth authorization endpoints and any *optional* SMART Capabilitise it supports using a [Well-Known Uniform Resource Identifiers (URIs)](#using-well-known) JSON file. (In previous versions of SMART, some of these details were also conveyed in a server's CapabilityStatement; this mechanism is now deprecated.)
+The server SHALL convey the FHIR OAuth authorization endpoints and any *optional* SMART Capabilities it supports using a [Well-Known Uniform Resource Identifiers (URIs)](#using-well-known) JSON file. (In previous versions of SMART, some of these details were also conveyed in a server's CapabilityStatement; this mechanism is now deprecated.)
 
 
 #### Capability Sets
@@ -99,6 +99,7 @@ completing the launch.
 ##### Permissions
 
 * `permission-offline`: support for refresh tokens (requested by `offline_access` scope)
+* `permission-online`: support for refresh tokens (requested by `online_access` scope)
 * `permission-patient`: support for patient-level scopes (e.g. `patient/Observation.rs`)
 * `permission-user`: support for user-level scopes (e.g. `user/Appointment.rs`)
 * `permission-v1`: support for SMARTv1 scope syntax (e.g., `patient/Observation.read`)
@@ -118,6 +119,12 @@ The authorization endpoints accepted by a FHIR resource server are exposed as a
 FHIR endpoints requiring authorization SHALL serve a JSON document at the location formed by appending `/.well-known/smart-configuration` to their base URL.
 Contrary to RFC5785 Appendix B.4, the `.well-known` path component may be appended even if the FHIR endpoint already contains a path component.
 
+Responses for `/.well-known/smart-configuration` requests SHALL be JSON, regardless of `Accept` headers provided in the request.
+
+* clients MAY omit an `Accept` header
+* servers MAY ignore any client-supplied `Accept` headers
+* servers SHALL respond with `application/json`
+
 #### Request
 
 Sample requests:
@@ -144,10 +151,10 @@ A JSON document must be returned using the `application/json` mime type.
 - `issuer`: **CONDITIONAL**, String conveying this system's OpenID Connect Issuer URL. Required if the server's capabilities include `sso-openid-connect`; otherwise, omitted.
 - `authorization_endpoint`: **REQUIRED**, URL to the OAuth2 authorization endpoint.
 - `token_endpoint`: **REQUIRED**, URL to the OAuth2 token endpoint.
-- `token_endpoint_auth_methods`: **OPTIONAL**, array of client authentication methods supported by the token endpoint. The options are "client_secret_post" and "client_secret_basic".
+- `token_endpoint_auth_methods_supported`: **OPTIONAL**, array of client authentication methods supported by the token endpoint. The options are "client_secret_post", "client_secret_basic", and "private_key_jwt".
 - `registration_endpoint`: **OPTIONAL**, if available, URL to the OAuth2 dynamic registration endpoint for this FHIR server.
 - `scopes_supported`: **RECOMMENDED**, array of scopes a client may request. See [scopes and launch context][smart-scopes]. The server SHALL support all scopes listed here; additional scopes MAY be supported (so clients should not consider this an exhaustive list).
-- `response_types_supported`: **RECOMMENDED**, array of OAuth2 `response_type` values that are supported
+- `response_types_supported`: **RECOMMENDED**, array of OAuth2 `response_type` values that are supported.  Implementers can refer to `response_type`s defined in OAuth 2.0 ([RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)) and in [OIDC Core](https://openid.net/specs/openid-connect-core-1_0.html#Authentication).
 - `management_endpoint`: **RECOMMENDED**, URL where an end-user can view which applications currently have access to data and can make adjustments to these access rights.
 - `introspection_endpoint` :  **RECOMMENDED**, URL to a server's introspection endpoint that can be used to validate a token.
 - `revocation_endpoint` :  **RECOMMENDED**, URL to a server's revoke endpoint that can be used to revoke a token.
@@ -167,7 +174,7 @@ Content-Type: application/json
   "token_endpoint_auth_methods_supported": ["client_secret_basic"],
   "registration_endpoint": "https://ehr.example.com/auth/register",
   "scopes_supported": ["openid", "profile", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
-  "response_types_supported": ["code", "code id_token", "id_token", "refresh_token"],
+  "response_types_supported": ["code", "code id_token", "id_token"],
   "management_endpoint": "https://ehr.example.com/user/manage",
   "introspection_endpoint": "https://ehr.example.com/user/introspect",
   "revocation_endpoint": "https://ehr.example.com/user/revoke",