SMART on FHIR Docs
License: Other
This is the SMART technical documentation, hosted at http://docs.smarthealthit.org
docker run -it --rm -v "$PWD":/usr/src/app -p "4000:4000" starefossen/github-pages
And then open a browser to http://localhost:4000
I've taken a stab at creating a sequence diagram for the launch sequences. In so doing, I've concluded that some of the detail currently in the "overview" section would fit more logically in the detailed description, but I can handle that later. First, I wanted you to look over the diagram.
A very important use case that I have not seen much about is the ability to write resources to the server; in particular for remote patient monitoring. Security (authorization, authentication, and data security) is critical in such an exchange. The Personal Connected Health Alliance (PCHA) has developed such standards for the delivery of device measurement data to the health care provider. These standards are used in the IHE Remote Patient Monitoring Profile. So far that exchange is based upon HL7 V2 messaging and the exchange of CCDA documents.
The PCHA use case with a standardized means to handle security is also needed for patient-administrated device data expressed as a FHIR Bundle. How would PCHA be able to get involved in the development of this process?
Thanks, Brian Reinhold
Should this specification touch on versioning for future versions?
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-72
The sequence diagram does not show the refresh_token included in the return from the Authorization Server, nor is the refresh_token exchange included.
Also, for confidential clients, authentication is required for both requesting authorization and for exchanging an access token for FHIR content. In the attached sequence diagram, I have corrected these omissions.
The page at Sandbox - Account Setup has a link ("register new apps") that is no longer valid:
You can register a new account for our public sandbox or manage your existing account by visiting our account self-service tool. Once you have an account in our system, you will be able to use our authorization service and register new apps on it.
Currently the http://docs.smarthealthit.org/authorization/scopes-and-launch-context/ page does not really explain how the launch URL parameter is meant to be used; in fact, one of the examples mentions launch=abc123, but looking at how the actual applications populate that parameter, it seems to me it is actually a JWT token with details about the launch context (e.g. patient etc.). Should this be clarified in that page?
Should the additional optional bits about intent and styling be included as a core part of the specification, or be handled as an optional extension specification? If those bits will change frequently, it may make sense to keep them separate.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-75
Refs: RFC6749; RFC 681
Risk Assessment Row: 2
Threat: Misinterpretation of OAuth 2.0 framework specification and threat model results in insecure implementation
Description: Authorization profiles assign actions relating to issuance of access tokens and refresh tokens to "authorization server" and actions relating to use of access token to retrieve a resource as "resource server."
Recommended Change: Clarify the actions of the OAuth 2.0 actors using the references “EHR Authorization Server” and “EHR Resource Server" in profiles. Revise diagram to show EHR resource server and EHR authorization server as separate actors.
In the server quick start:
FamilyHistory of the patient, not just for the weight/height/BMI observationscode without the corresponding system, that is compulsory if code is specifiedDo any of these scopes allow for whole system interactions?
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-73
Here's a draft of a diagram showing use of access token to retrieve FHIR resource, and exchange of refresh token for new access token.
Are these restricted to purely web schemes, or are native application redirects allowed? That particular detail imparts some requirements on an authorization server.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-80
Are we requiring EHRs to be identity providers, thus requiring them to implement section "15.1. Mandatory to Implement Features for All OpenID Providers" for OpenID Connect? This adds quite a bit to the EHR's requirements, and will require running EHRs through the OpenID Connect conformance features. This also gets QUITE complicated if the EHR itself is an OpenID Connect relying party... it has to pass-through much of the functionality to the upstream OIDC IdP.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-76
I added the following as the question was repeatedly raised as to whose responsibility it was to react to and fix problems that occur with security. I'm interested in feedback on this proposal.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-82
Hi there,
Just questioning if there is an alternative to the options around launch scopes / what the thinking is around coupling the authorisation service with launch context.
The approach for passing launch context (via authorisation server as part of issuing an access token) seems based on the premise that our system can modify the behaviour of the authorisation server. We are utilising a 3rd party API Manager (and I assume a lot of others would look to do so as well). Conflating passing of session information / launch context in with this token means we need to look to modify a 3rd party product which we'd rather not do. Are there other options on the table to achieve similar without the underlying assumption that we can modify the authorisation server? E.g. a FHIR Other resource or similar where the lookup of launch scope can be done on the backend? I can imagine a lot of companies would look to use COTS API Managers and the current approach makes adoption of this hard for those of us that do.
Thanks,
Will.
Currently the format for user/patient scope looks like:
patient/:resourceType.(read|write)
The issue is that 'read' effectively means reading data and 'write' means that you can create/updated/delete data. You can imagine situations where you allow user to read/update data but you don't want him to have delete patient data privilege.
Is it possible to extend it to cover at least delete as separate privilege?
patient/:resourceType.(read|write|delete)
[New Profile]
Description: The introductory paragraph ends with a colon.
Recommendation: Add "Does the app have the capability to “keep a secret?” after colon
In certain workflows, the authorization server will need to request the user to authenticate. Since the mechanism used by providers and patients will likely be different, how do we disambiguate the nature of the access for the authorization server to appropriately send them to the right place to log in? Since services for patients and providers might have different conformance properties, should it just be recommended that they are implemented as different FHIR base URLs?
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-77
Currently, the SMART specification defines scopes like patient/*.read and launch. In the current Argonaut branch, it is mentioned that scopes may need to be represented as URIs and defines a URI pattern to follow.
Per rfc6749:
Unregistered vendor-specific parameter extensions that are not
commonly applicable and that are specific to the implementation
details of the authorization server where they are used SHOULD
utilize a vendor-specific prefix that is not likely to conflict with
other registered values (e.g., begin with 'companyname_').
For consistency, and to ensure SMART's scopes do not conflict with other scopes the authorization server may be handling, all SMART scopes should be prefixed. Going with the current Argonaut documentation, this would be requiring that all scopes are prefixed with http://smarthealthit.org/fhir/scopes. For reference, here are the currently registered OAuth 2 parameters.
On a related topic, SMART should also prefix the SMART specific parameters that are returned with the access token -- both for consistency and to avoid possible collisions with other token parameters the authorization server may be returning. However, rfc6749 does not explicitly require or recommend this:
The client MUST ignore unrecognized value names in the response. The
sizes of tokens and other values received from the authorization
server are left undefined
// cc @whitehatguy since some of this is also called out in your white paper:
A name-spacing mechanism to prevent collisions with other specifications that utilize scopes.
@jmandel - Let me know if this sounds good. If so, I will start on a pull request to update the argonaut documentation around this
I've been modifying this demo on JSfiddle to use as a demo on NutritionOrder at HIMSS. I noticed I can't point to any endpoint like Grahame's open server. I'm not pretending I know what is happening under the hood with the authorization and certificates, but HAPI works if I change the endpoint from 'http' to 'https' and the browser complains about the certificate, but Grahame's server just claims the patient is not found. ( its there I can access it from the browser eg/ Patient/111). Any explanation or solution would be great.
Thanks,
Eric
Should we have a global revocation mechanism for client credential keys? I suggest a JWK endpoint, allowing clients to rotate keys, and more critically, allowing them to revoke keys. Such documents could self-describe their caching requirements via standard HTTP semantics.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-83
Re 2.1.2: "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:
Support for single sign-on.
Support for anti-phishing controls implemented via persistent browser state or browser plug-ins.
Support for external native applications for sign-on.
External regulatory requirements that would prohibit user credentials from being entered via an embedded browser within the SMART application.
Such "native" applications MAY support orchestrating the authorization flow in an embedded browser where requested out-of-band by the EHR provider."
An OS's "default browser" is not always (perhaps "rarely") the most secure configuration, nor even the configuration required by institutional policy. Further, this kind of materials is more appropriately contained in implementation guidance, not in a core profile. I suggest deleting all of the content above.
Ref: RFC6749; RFC6819
Risk Assessment Row: 2
Description: Current profiles combine OAuth2 Authorization Server and Resource Server actors into one "EHR" actor, which creates ambiguity in interpretation.
Recommendation: Replace sequence diagram in confidential client authorization profile to the following:
We went through the FHIR resources associated with the SMART profiles and found some discrepancies that we wanted to make you aware of (see attached). Please let us know if the assumptions we've made about the field and resource name updates are correct (rows 2-10). Please also let us know what we should do about the fields SMART specifies should be present but are not in the FHIR resource (rows 11-15).
Thank you,
Craig
SMART Profile Documentation - Problem Fields.xlsx
@bakerdb The current draft says:
But it's unclear what this means. For which parties (apps or servers) is this "recommended"? I'd imagine some servers would require it, which means it's really not optional for apps. If we want to go this route, and offer this mitigation, then we need to say something stronger about it, from the app's perspective.
I am going to tranlate your SMART doc and localize some sdk ,is this ok?
Exactly what happens in a scenario where a website needs to change its issuer value? Perhaps an organization is re-named. What about the permanency of identifiers? Should an opaque identifier be used for individuals, in the event that other identifying information changes in the underlying implementation? Should this be in a format to support web-finger to allow future authentication-only? Since advertising the location of the authorization and token endpoints are required in the OpenID Provider Configuration document, should implementations make best effort to make those the same as the authorization endpoints for SMART/FHIR? What happens if a non-passive change occurs that breaks compatibility?
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-78
http://docs.smarthealthit.org/authorization/scopes-and-launch-context/
section User-level scopes ,the final rows
Manage all resources on behalf ot he authorizing user
user/.read user/.write
Note that the permission is broader than our goal: with this scope, an app can add not only blood pressures, but other observations as well.
why blood pressures?
If the OpenID Connect protocol is legitimately being used for authentication, the steps currently listed for validating an ID token should instead refer individuals to section 3.1.3.7 of the OpenID specification for validation steps. There are certain key elements, such as validating the audience that are necessary.
In addition, step 6 of section 3.1.3.7 states:
"If the ID Token is received via direct communication between the Client and the Token Endpoint (which it is in this flow), the TLS server validation MAY be used to validate the issuer in place of checking the token signature."
Should we make this explicit in this profile to reduce the overhead of having to support the .well_known endpoint along with hosting signature keys? There's little additional security afforded here, unless consumers want to somehow utilize such id_tokens within their own internal security implementation.
Finally, the use of OpenID Connect seems to transitively place requirements on the authorization server to support the following parameters in the authentication request. This should likely be explicitly stated in the documentation:
Other optional functionality would also need to be indicated that it is not supported per the OpenID Connect Discovery specification. An example is "Passing a Request Object by Value" as described by section 6.1 in the Connect Core spec.
Is the intent here to have EMRs act as full-blown authentication servers (and/or as proxies to the authentication system that they use internally)? It would seem that passing the FHIR endpoint for the user could be easily achieved as an additional claim. I haven't seen any Argonaut use case that calls out utilizing the authorization server solely as an authentication system.
The current authz profile layout is confusing, with six steps of "Examples" followed by six very similar steps of "Details". These should be merged into a single stream of details with inline examples.
The authorization guidance here: http://fhir-docs.smarthealthit.org/argonaut-dev/authorization/
Includes an image with an example of the request made to the authorization url. This image should be replaced with one that includes the required "aud" parameter.
The current draft of the Argonaut authorization profile for use case #5 (EHR-to-EHR access) states that the "exp" parameter specified in the authorization and authentication JWTs passed from EHR-A to EHR-B "MUST be no more than five minutes in the future." Thinking about the possibility that such accesses might be for bulk transfers (e.g., transition of care), it seems to me that the "exp" value for the authorization JWT might enable access for a longer time period (say several hours), while the "exp" value for the authentication JWT should remain at no more than 5 minutes.
I'm interested in hearing your thoughts about this.
Since this is a different diagram, I'm starting a new issue. I started with your suggestion from Issue #37 regarding the Authorization sequence, cleaned it up (e.g., it had both "EHR" and "EHR Authz Server" as separate actors, though "EHR" is not an actor in this one), added explanatory notes, and also added id_token and refresh_token to the authz return. Here's the result:
If an app has to re-request access to a resource whose authorization was originally obtained via a
launch, how does it request that? Currently, scopes only define single-resource access via launch scopes, or access to the entire set available to the user.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-71
Can the growth-chart app(or others) be launched standalone without the request having to generate from an EHR?
-If it's possible then what customizations are needed to be done in the launch.html file?
-Or is the standalone launch meant for mobile apps only?
Thanks
When should client authentication be a required element? There should be a specific threat that needs to be addressed, rather than simply "be capable of protecting a secret" -- otherwise, folks might choose to not use client authentication when it really should be doing so. The below is my recommendation. In addition, this prescribes the use PKI mechanisms in-line with the proposed EHR-to-EHR bits.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-79
Location should not be a standard launch context parameter because a clinical location in which the app is being used already exists in the Encounter resource's class and Location elements.
Additionally, very few and perhaps no production FHIR server support Location yet. I think that no one has actually implemented a launch parameter specifying to specify a FHIR Location resource (unlike Patient and Encounter).
Pull request #132
Hello sir,
their is any example of Standalone launch sequence application in javascript.
Ref: OIDC (16.7)
Risk Assessment Row: 40
Description: As a countermeasure for request repudiation, the OpenID Connect spec recommends having the client digitally sign requests using a key that supports non-repudiation, with the AS validating the signature.
Recommendation: Considering adding request non-repudiation to the profile.
URL to editable diagram is at https://www.websequencediagrams.com/?open=78051
At step 4 here the request should include also client_id=app-client-id
Currently, there doesn't seem to be a way for a client application to convey that it desires permanent access on behalf of a user versus short-lived access. A given application may have both modes of operation, and a given EHR administrator may wish to restrict the "offline access" scenario without impeding the short-lived access use case. Additionally, I don't think it is reasonable to configure an authorization server to always hand out offline access tokens for both scenarios, as that's something you'd likely want to prompt the user to explicitly approve, and the user might be using a workflow that only requires short-lived access.
If I had to make a proposal, I would propose a special scope of "offline". This scope's semantic would indicate that the resulting grant is for use by the client application when the user is offline. It would allow an authorization server to disambiguate whether a given request requires short-lived or long-lived access.
HEART is proceeding with the use of JWK URIs for keys for client authentication -- I'm pretty much in agreement with that approach; can we list that as a registration requirement for client apps that need authN?
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-81
I know I'm a total noob for asking this, and I know the answer to this is probably obvious....but whenever I click on the link "sign into our sandbox" on the http://docs.smarthealthit.org/tutorials/testing/ page, a patient search web app of some sort launches, and an error is immediately displayed.
This is the error: "Search failed, see console"
I swear I wasn't getting this error before (last week). Essentially, I'm trying to test my app using the sandbox. Any help would be greatly appreciated.
Ian
The examples for the profile need to be updated.
It's often important for an app being accessed by multiple health systems to receive an identifier, when the app is launched from the EHR, that uniquely describes the health system.
In practice, this technique is widely and consistently implemented to accomplish auditing and even billing based upon usage. Ultimately, the needs of the app dictate a health system identifier. This identifier is consumed by the app and can either be specified by the app, or could be some type of tenant identifier from the EHR, or could even be a department or facility identifier.
I typically see this identifier named something like "healthsystem" or "client".
Any suggestions for a great name for this launch parameter?
Are there situations where the scope "launch" would be denied and the workflow would be expected to continue uninterrupted? We've found a lot of people forget the "launch" scope when making the request, which leads to confusion, as they get a token back without any of their launch information. It seems like simply having the extension should be sufficient.
In-context at: http://fhir-docs.smarthealthit.org/argonaut-dev/specification/#q-issue-74
Ref: RFC6749 (10.2)
Risk Assessment Row: 3
Description: Current profiles indicate that asking the end user to authorize the client is "optional." No information is included regarding how the AS requests authorization from the end user, or what information is provided to the end user.
Recommendation: Revise the first two paragraphs under "EHR [AS] Evaluates Authorization Request" to the following:
"The decision rules and process are up to the EHR AS. The EHR AS will enforce rules based on local policy, and optionally will ask the end-user to authorize the app to access that user’s EHR information. If an EHR launches the app for an authenticated user who has explicitly requested the launch, asking for the end user's authorization is optional; else the user's authorization SHOULD be requested.
To obtain end-user authorization, the EHR AS authenticates the identity of the end-user (the method of authentication is outside the scope of this profile) and provides the user information regarding the client, and the resource, scope, and time for which access is being requested. The end-user responds by either granting or denying the access request."
In the specification draft, the following definition is made for "electronic health record":
Computer software designed to store and process information about a person's health information, such as medications, allergies, medical history, etc. The EHR acts as a resource server by providing FHIR services, is responsible for authenticating end users, and is responsible for providing an authorization server.
@bakerdb provided the following feedback:
... we've made a conscious effort not to dictate architecture, such as by assuming that the "EHR" is the resource server, authorization server, and client.
It was further indicated that the Argonaut use case documentation provides the following definition:
We use “EHR” in a broad context inclusive of any system that holds and controls individually identifiable health information. Each EHR system has the capability to mediate app requests for access and to authorize access to FHIR resources."
Existing developer documentation 2 refers to entities such as "EHR FHIR server" and "EHR authorization server". How might we best describe the EHR's as an actor in this ecosystem with respect to the FHIR resource server and the authorization server?
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.