Difference between revisions of "201709 Consumer Centered Data Exchange"
Aaron Seib (talk | contribs) |
m |
||
(93 intermediate revisions by 4 users not shown) | |||
Line 6: | Line 6: | ||
==Submitting WG/Project/Implementer Group== | ==Submitting WG/Project/Implementer Group== | ||
− | FHIR Product Director, in association with Society for Participatory Medicine, MIHIN, NATE, DXC. Interested committees: FHIR-I, CBCC, Security, PA, PC, OO | + | FHIR Product Director, in association with Society for Participatory Medicine, MIHIN, NATE, DXC, Cerner (SoF Scenario only). Interested committees: FHIR-I, CBCC, Security, PA, PC, OO |
==Justification== | ==Justification== | ||
− | In the connectathon process, we've tested narrow scenarios around data exchange, but interest is growing quickly to understanding | + | In the connectathon process, we've tested narrow scenarios around data exchange, but interest is growing quickly to increase understanding of Consumer Centered Directed Exchange. |
− | Consumer Centered | + | Consumer Centered Data Exchange can be thought of as a category of use cases including: |
− | *Consumer Access - in these use cases data held by a Source EMR is transferred to a Consumer Controlled App (CCA). | + | *Consumer Access (CA) - in these use cases data held by a Source EMR is transferred to a Consumer Controlled App (CCA). |
− | *Consumer | + | *Consumer Initiated Exchange (CIE) - in these use cases the actions of a Consumer result in the transfer of data from a Source EMR to a Target EMR ''(via Consent or otherwise where the data is exchange amongst Covered Entities at the Direction of the Consumer and is not TPO)'' |
− | *Consumer Directed Exchange - in these use cases | + | *Consumer Directed Exchange (CDE) - in these use cases data held by a CCA is transferred to a Target EMR |
− | The justification for this track is to develop an understanding of what - if anything - the main specification | + | The justification for this track is to develop an understanding of what - if anything - the main specification of the US core IG should say about enabling these consumer-centric use case. |
==Proposed Track Lead== | ==Proposed Track Lead== | ||
Grahame Grieve (mentoring Aaron Seib to take over after this) | Grahame Grieve (mentoring Aaron Seib to take over after this) | ||
+ | |||
+ | == Summary== | ||
+ | Presentation from wrap-up: | ||
+ | |||
+ | https://docs.google.com/a/medyear.org/presentation/d/1qahhq4FqQawz2VE1YMh1liDQqWwvfiiKkn1exu6WCuo/edit?usp=sharing | ||
+ | |||
+ | ==Zulip stream== | ||
+ | |||
+ | For discussion purposes, the following thread should be used on the FHIR Chat | ||
+ | |||
+ | https://chat.fhir.org/#narrow/stream/connectathon.20mgmt/topic/C16.20Consumer.20Centered.20Data.20Exchange | ||
==Expected participants== | ==Expected participants== | ||
− | NATE | + | |
− | MIHIN | + | * NATE |
− | DXC | + | * MIHIN |
+ | * HSS IDEA Lab Authors of the POET specification Mark Scrimshire & Alan Viars | ||
+ | * http://test.fhir.org/r3 | ||
+ | * Cerner (for SoF scenarios only) | ||
+ | * EMR Direct | ||
+ | * DXC | ||
+ | * CareEvolution | ||
+ | * GetRealHealth | ||
+ | * Humetrix | ||
+ | * MedFusion | ||
+ | * [mailto:johnmoehrke@gmail.com John Moehrke] (HL7 Security co-chair) SME on FHIR Consent | ||
+ | |||
(others: email aaron.seib@nate-trust.org if you are interested in getting involved) | (others: email aaron.seib@nate-trust.org if you are interested in getting involved) | ||
Line 40: | Line 62: | ||
The scenarios being proposed in this track describe several methods that may enable Paul "to cause" this transfer. | The scenarios being proposed in this track describe several methods that may enable Paul "to cause" this transfer. | ||
− | Assumptions: we intended to reuse and extend as necessary existing capabilities developed to date by the FHIR-community including | + | Assumptions: we intended to reuse and extend as necessary existing capabilities developed to date by the FHIR-community including: |
− | *the Argonaut interface - | + | *the Argonaut interface - leverage the ability to access data from an EMR that is provided by an Argonaut based patient portals; |
− | *SMART-on-FHIR | + | *SMART-on-FHIR; |
*Various FHIR resources such as the Consent resource; and | *Various FHIR resources such as the Consent resource; and | ||
*Others as identified. | *Others as identified. | ||
− | |||
See '''Relevant Specs and Documentation''' below. | See '''Relevant Specs and Documentation''' below. | ||
Line 52: | Line 73: | ||
* Consumer Controlled App: the CCA of Paul's choice | * Consumer Controlled App: the CCA of Paul's choice | ||
− | * Source EMR system: the | + | * Source EMR system: the Specialist EMR that will make the data available |
* Target EMR system: the VA or equivalent system that will acquire the data | * Target EMR system: the VA or equivalent system that will acquire the data | ||
− | * | + | * Consumer App Verification Service: a service that verifies 'Claim(s)' made by an App for a relying party when a use case performs "Application Verification" |
+ | * eConsent Management System: a service performed by an HIN that acts as a relay to end-points | ||
== Authorization pattern == | == Authorization pattern == | ||
− | There are | + | There are 8 possible patterns for Authorizing/Managing the data flow |
− | 1. Provider to Provider | + | *1. Provider to Provider via SMART on FHIR Consumer Initiated Exchange (P2P via SoF CIE) |
− | 2. Provider to Provider with | + | *2. Provider to Provider via SMART on FHIR Consumer Initiated Exchange with Consent (P2P via SoF CIE with Consent) |
− | 3. Provider to | + | *3. Provider to Consumer via SMART on FHIR Consumer Access (P2C via SoF CA) |
− | 4. Provider | + | *4. Consumer to Provider via SMART on FHIR Consumer Directed Exchange (C2P via SoF CDE) |
− | 5. Provider to | + | *5. Provider to Provider via Direct Secure Messaging with Consent (P2P via DSM with Consent CIE) |
− | 6. | + | *6. Provider to Consumer via Direct Secure Messaging with Individual Right of Access request (P2C via DSM with IRA CA) |
− | 7. Full UMA | + | *7. Full UMA |
+ | *8. P2P via HIN with eConsent Management Service | ||
− | === 1. | + | === 1. P2P via SoF CIE === |
Data is made available to a target EMR by the normal SMART on FHIR interface (see http://docs.smarthealthit.org/authorization/). | Data is made available to a target EMR by the normal SMART on FHIR interface (see http://docs.smarthealthit.org/authorization/). | ||
In this scenario: | In this scenario: | ||
− | * Paul logs into the target EMR app ( | + | * Paul logs into the target EMR app (EHR launch via the EMR's Patient Portal), and informs the app that he wants to connect it to the source EMR (how this is done is outside the scope of the connectathon) |
* The target EMR app (re)directs Paul to the authorization URL on the source EMR | * The target EMR app (re)directs Paul to the authorization URL on the source EMR | ||
* Paul authorizes the application as he wants | * Paul authorizes the application as he wants | ||
Line 84: | Line 107: | ||
* there is no new API/interface in this arrangement - all of this is as described today, with additional application work. | * there is no new API/interface in this arrangement - all of this is as described today, with additional application work. | ||
− | * this is actually more complicated than a simpler alternative: Paul has an application that downloads content from the source, and uploads it to the target. This approach has 2 problems - there's no trust (provenance) associated with the target/source connection (and there's plenty of real world demonstration that this is a big problem for care providers) and flow of data depends on Paul's devices and connectivity. There is solid grounds for Paul being able to download/update data to EMRs, but this connectathon stream focuses on giving the customer control over direct data flow | + | * this is actually more complicated than a simpler alternative: Paul has an application that downloads content from the source, and uploads it to the target. This approach has 2 problems - there's no trust (provenance) associated with the target/source connection (and there's plenty of real world demonstration that this is a big problem for care providers) and flow of data depends on Paul's devices and connectivity. There is solid grounds for Paul being able to download/update data from/to EMRs, but this connectathon stream focuses on giving the customer control over direct data flow |
+ | |||
+ | Assumptions for this Connectathon: | ||
+ | * The target EMR is registered with the source EMR before the scenario begins. | ||
+ | * The source EMR's Conformance Statement is known to the target EMR. | ||
+ | * The source EMR provides Paul a method to revoke his authorization. | ||
− | + | === 2. P2P via SoF CIE with Consent === | |
− | |||
− | + | Similar to scenario 1 - | |
− | Data is made available by the normal SMART on FHIR interface with a consent layer. | + | Data is made available to a target EMR by the normal SMART on FHIR interface with a consent layer. |
In this scenario: | In this scenario: | ||
* Paul authorizes an app to the source EMR (http://docs.smarthealthit.org/authorization/) | * Paul authorizes an app to the source EMR (http://docs.smarthealthit.org/authorization/) | ||
− | * Paul posts a Consent resource to the server, or chooses an existing consent statement | + | * Paul posts a Consent resource to the server, or chooses an existing consent statement. |
− | * Paul asks the source server for an | + | * Paul asks the target server for it's identifying token (see 'Acquiring an Applications JWT' below) |
+ | * Paul asks the source server for an access token for the target server based on the consent (see 'Authorizing an Application' below) | ||
* Paul authorizes with the target server, and gives it the API token (see 'Providing API token' below) | * Paul authorizes with the target server, and gives it the API token (see 'Providing API token' below) | ||
* the target EMR makes requests of the source system in an ongoing fashion using the API token | * the target EMR makes requests of the source system in an ongoing fashion using the API token | ||
Line 104: | Line 132: | ||
This scenario requires Paul to know the URLs for both source and target, and to | This scenario requires Paul to know the URLs for both source and target, and to | ||
have apps authorized to both of them (could be the same app) but he doesn't have to | have apps authorized to both of them (could be the same app) but he doesn't have to | ||
− | deal with multiple applications, and trust relationships between them are not required | + | deal with multiple applications, and trust relationships between them are not required. |
− | === 3. Provider to Provider with Consent | + | === 3. Provider to Consumer via SoF Consumer Access === |
+ | |||
+ | Similar to Scenario 1 except in the place of a Target EMR, Paul is requesting Data be sent to his CCA | ||
+ | |||
+ | Data is made available to the CCA by the normal SMART on FHIR interface (see http://docs.smarthealthit.org/authorization/). | ||
+ | |||
+ | In this scenario: | ||
+ | |||
+ | * Paul logs into the CCA and informs the app that he wants to connect it to the source EMR (how this is done is to be explored as part of the connectathon). | ||
+ | * The source EMR may perform Application Validation to verify that the CCA has sufficient endorsements per local policy to support this use case. | ||
+ | * The CCA (re)directs Paul to the authorization URL on the source EMR. | ||
+ | * Paul authorizes the application as he wants. | ||
+ | * the CCA makes requests of the source system in an ongoing fashion per SMART on FHIR. | ||
+ | * Paul connects to the source EMR to revoke his authorization when he wants the data flow to end. | ||
+ | |||
+ | This scenario requires Paul to know the URLs for the source EMR and to have an account with a FHIR-enabled CCA. | ||
+ | Dynamic App registration is out of scope for this connectathon meaning that the CCA must be registered to the source EMR prior to the start of the scenario. | ||
+ | Paul must deal with multiple applications, and is dependent on trust already existing between the Source and the CCA. | ||
+ | The Source EMR may perform Consumer Application Verification periodically on the CCA in question by following the Application Verification process. | ||
+ | |||
+ | === 4. Consumer to Provider via SoF Consumer Directed Exchange === | ||
+ | |||
+ | This scenario is similar to scenario 2 except instead of data flowing from the Source EMR to the Target EMR (Institution to institution) a Consumer Controlled Health App is the Source. With the Consumer directing the flow of data a consent layer is not required but to support the Target EMR’s trust in the Consumer App we invoke Application Verification when the target EMR may wish to verify that the Consumer App identified in the $authorize operation is acceptable to it. To do this, the target EMR can take the public key provided in the "publicKey" parameter of the $authorize operation, and send it to a 3rd party Consumer Application Verification Service (CAVS) that it trusts to provide advice similar to the interactions between a Source and Target EMR in scenario 2. | ||
+ | |||
+ | * Paul authorizes his consumer controlled app (CCA) to release selected content to a target EMR | ||
+ | * Paul asks the target server for it's identifying token (see 'Acquiring an Applications JWT' below) | ||
+ | * Paul asks the source server for an access token for the target server based on the consent (see 'Authorizing an Application' below) | ||
+ | * Paul gives the target server the API token (see 'Providing API token' below) and the “publicKey” of the CCA | ||
+ | * The target EMR invokes Application Verification using the “publickey” and a local policy engine to determine if it “trust” the Consumer App for this use case. | ||
+ | * The target EMR makes requests of the CCA (which implies to me that this could be discovered via the same registry as the one used to check for endorsements) for the content using the API token. | ||
+ | |||
+ | This scenario requires Paul’s CCA to know the target EMR’s URL for this use case (CDE). This scenario also requires the target EMR to know the location of the 3rd party server that Paul’s CCA is registered with to retrieve the endorsements associated with that CCA for evaluation by the target EMR’s local policy engine. In this scenario a precondition is that the Consumer Controlled App has content that the consumer wishes to share with the target EMR. | ||
+ | |||
+ | === 5. P2P via DSM with Consent === | ||
In this scenario, data is made available in the same format as Argonaut, but | In this scenario, data is made available in the same format as Argonaut, but | ||
Line 124: | Line 185: | ||
multiple applications, and trust relationships between them are not required | multiple applications, and trust relationships between them are not required | ||
− | === | + | === 6. P2C via DSM with IRA request === |
In this scenario, data is made available in the same format as Argonaut, but | In this scenario, data is made available in the same format as Argonaut, but | ||
− | instead of a Pull based API, a push using Direct is used | + | instead of a Pull based API, a push using Direct is used. |
In this scenario: | In this scenario: | ||
* Paul authorizes his CCA to the source EMR (standard SMART on FHIR) | * Paul authorizes his CCA to the source EMR (standard SMART on FHIR) | ||
− | * Paul posts an Individual Right of Access request to the server | + | * Paul posts an Individual Right of Access request (profile of a Consent Resource) to the server |
* Paul asks the source EMR to start pushing the data based on the consent (see 'Starting push' below) | * Paul asks the source EMR to start pushing the data based on the consent (see 'Starting push' below) | ||
* the source EMR sends data to the his CCA using direct based push | * the source EMR sends data to the his CCA using direct based push | ||
* Paul can stop the sending through the source EMR (see 'Stopping push' below) | * Paul can stop the sending through the source EMR (see 'Stopping push' below) | ||
− | NOTE: | + | NOTE: |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | This scenario | + | This scenario creates an opportunity to explore how a Consumer's Direct Address could be "passed" to an EMR to be used in subsequent "Pushes". |
− | + | It relies on the SoF mechanism to enable the posting of an IRA to the source EMR. | |
− | + | It would require the source EMR to implement a process to "start" and "stop" the sending of Content. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== 7. Full UMA === | === 7. Full UMA === | ||
Line 180: | Line 219: | ||
Note: this builds on the Argonaut interface by adding HEART/UMA support to it. This scenario requires the target EMR to know the source EMR’s FHIR URL, but knowledge of the UMA AS URL is not required. The source EMR has previously delegated authorization to Paul's data (resource set) to the UMA-enabled AS and the AS is able to authenticate the target EMR. | Note: this builds on the Argonaut interface by adding HEART/UMA support to it. This scenario requires the target EMR to know the source EMR’s FHIR URL, but knowledge of the UMA AS URL is not required. The source EMR has previously delegated authorization to Paul's data (resource set) to the UMA-enabled AS and the AS is able to authenticate the target EMR. | ||
+ | |||
+ | === 8. P2P via HIN with eConsent Management Service === | ||
+ | |||
+ | In this scenario a veteran is admitted to a non-VA substance use disorder treatment facility that receives federal funding and is thus subject to 42 CFR 2 requiring written patient consent for the facility to share SUD-related information (including the fact of admission) with “name recipients” from the patient’s consent form. | ||
+ | |||
+ | To facilitate this scenario a simulated Health Information Network operating an electronic Consent Management Service (eCMS) facilitates sharing with the consumer’s Care Team with the consumer’s consent. | ||
+ | |||
+ | The scenario participant is able to create a consent for a consumer Persona (synthetic patient). Complete Persona information will be provided for each scenario participant. Each scenario participant will enter basic demographic information from the Persona data into a (provided) “Consumer Portal” (which is embeddable) and will use this to create an electronic consent which is then automatically sent to the HIN and stored in the eCMS based on the demographic information on the consent form which the HIN uses to match the patient to a list of authorized recipient derived from the “metadata” in the electronic CMS taken from the electronic consent form in the portal. | ||
+ | |||
+ | The 42 CFR 2 SUD treatment facility now wishes to send the “Admission Discharge Transfer” (ADT) notification (provided to scenario participants in HL7 v2 test data / pipe delimited text) with the HIN so the HIN can broadcast this ADT notification to all named recipients from the patient consent form. Source EMRs are able to check if there is a consent on file for for their consumer Persona by querying the eCMS (using FHIR). If there is a valid consent on file for that consumer in the query, the eCMS notifies the source EMR and the source EMR is able to insert privacy tags in content (an ADT – test data is provided) and send content (the ADT with test data) to the HIN which then uses information from the eCMS to distribute the data to authorized end users (e.g. the consumer’s named recipients). | ||
+ | |||
+ | In this scenario: | ||
+ | |||
+ | • The consumer (e.g. the scenario participant) fills in the standard electronic consent form on the (embeddable) consumer portal page which then posts both a Contract resource and a Consent resource to the eCMS server. | ||
+ | |||
+ | • This consent, if valid, authorizes the sEMR to share data with the HIN (which subsequently distributes the data to the authorized end-points) | ||
+ | |||
+ | • A source EMR wants to send an ADT to the authorized end-points associated with their consumer Persona in the eCMS. | ||
+ | • The source EMR queries the eCMS to find out if there is a consent for their consumer Persona. | ||
+ | |||
+ | • If there is no matching consent in the eCMS the source EMR does nothing further. | ||
+ | |||
+ | • If there is a matching consent in the eCMS then the source EMR (a) first inserts a “privacy tag” (the letters “SPI”) into the “security label” field of the HL7 v2 ADT and then (b) sends the (test) ADT containing the privacy tag to the HIN (simulated) which then queries the eCMS to determine “named recipients” from the electronic consumer’s consent form and finally broadcasts the (test) ADT to the authorized end points (simulated) for those named recipients (in accordance with SAMHSA 42 CFR 2). | ||
+ | |||
+ | • When the HIN receives an ADT it first checks to see if a privacy tag is contained in it and if so, the HIN matches the patient to the consent metadata stored in the eCMS to retrieve a list of authorized end-user electronic end-points and then the HIN distributes the ADT to the consumer’s named recipients in conformance with the Consent. | ||
+ | |||
+ | • The consumer Persona (scenario participant) can revoke the consent that is posted to the eCMS server at any time. | ||
== Interfaces == | == Interfaces == | ||
=== For pattern #2 - Provider to Provider with Consent CCDE === | === For pattern #2 - Provider to Provider with Consent CCDE === | ||
+ | |||
+ | 4 parties: | ||
+ | * patient : orchestrates the connection, connected to 2 different EHRs | ||
+ | * target EHR: will be asked to pull data from the source EHR using it's argonaut interface | ||
+ | * source EMR: will be authorised to provide data to the source EHR on behalf of the patient | ||
+ | * Application Endorser: source ER may use this to verify how much it trusts the target | ||
+ | |||
+ | note: identification of the target EHR is based on a JWT. The JWT should include a "sub" that names the target EHR. It may also include an expiry date. The JWT must be signed. The suitability of a JWT is open to debate - JWK and/or a simple public key are alternatives with different pros and cons. | ||
==== Authorizing an Application ==== | ==== Authorizing an Application ==== | ||
− | POST [base]/Consent/[id]/$authorize | + | Call this on on the source EHR: |
+ | |||
+ | POST [base]/Consent/[id]/$authorize | ||
Inbound Parameters: | Inbound Parameters: | ||
− | * | + | * jwt : string - a JWT that identifies the target EHR (see below for how to get that) |
− | * duration : Duration - how long the token should be good for. (optional: default to Consent.period if not provided) (cannot be be for longer than the consent itself) | + | * duration : Duration - how long the token should be good for. (optional: default to Consent.period if not provided) (cannot be be for longer than the consent itself, or the expiry in the JWT) |
Response: 200 ok with Parameters, or an error with an operation outcome. Outbound Parameters: | Response: 200 ok with Parameters, or an error with an operation outcome. Outbound Parameters: | ||
* duration : Duration - maximum length of time that the token is going to be honored. No duration means that the approval is not time limited | * duration : Duration - maximum length of time that the token is going to be honored. No duration means that the approval is not time limited | ||
+ | * authorization : a token that identifies the authorization - used later by the target EHR | ||
− | The | + | The source EHR returns an error if it is not able to understand the consent resource fully, or if it is not prepared to honor |
the consent statement (e.g. it probably won't agree to a consent that grants more than the granting application itself | the consent statement (e.g. it probably won't agree to a consent that grants more than the granting application itself | ||
has been authorized to have), or if it refuses to authorize the specified application for some reason (see below for | has been authorized to have), or if it refuses to authorize the specified application for some reason (see below for | ||
− | further discussion on the implementation and policy of this). | + | further discussion on the implementation and policy of this). The source EHR should verify the signature on the JWT, and may choose to verify the client (see below) |
+ | |||
+ | The user of the client - usually, but not necessarily - a human - chooses the Consent on which to base $authorise the target EHR. Note that the only system that computes with this consent is the source EHR, which provides the consent itself; no other system needs to compute with the consent (the patient's software just has to let the patient choose a consent). Note: the source EHR may let the patient provide the consent through the client - that is a different transaction that is out of scope for this connectathon | ||
− | + | If a computable consent is required, this is the suggested template: | |
<Consent xmlns="http://hl7.org/fhir"> | <Consent xmlns="http://hl7.org/fhir"> | ||
Line 246: | Line 325: | ||
− | + | Note: This profile is a restricted form of the Consent resource that allows the user to consent using Smart on FHIR scopes | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==== Acquiring an Applications JWT ==== | ==== Acquiring an Applications JWT ==== | ||
− | The operation above requires that the client have a | + | The operation above requires that the client have a JWT that identifies the target EHR. This is done by calling [base]/$jwt?source=[url] on the target EHR, where source is the S4S endpoint from the source EHR. The target EHR returns a body of type application/jwt that contains the JWT that the target wishes to use to identify itself to the source EHR. Note that source is a mandatory parameter, but it is up to the target EHR whether to use it's standard JWT or to make up a single use JWT. |
==== Application Verification ==== | ==== Application Verification ==== | ||
− | The source EMR may wish to verify that the target EMR identified in the $authorize operation | + | The source EMR may wish to verify that the target EMR (or the CCA in Scenario 3) identified in the $authorize operation is acceptable to it. it can perform this operation either when $authorize is called, or when the target EHR connects to it (see below). |
− | is acceptable to it. To do this, the source EMR can take the | + | |
+ | To do this, the source EMR can take the jwt provided in the "jwt" parameter of the $authorize operation, and send it to Client App Validation service that provides information about what endorsements are verifiably attributed to the target EMR (or CCA as the case may be). | ||
+ | |||
+ | POST [base] | ||
+ | Content-Type: application/x-www-form-urlencoded | ||
+ | |||
+ | jwt=[jwt] | ||
+ | |||
+ | where [base] is the URL of the CAVS (client application verification service). The CAVS will return a json object listing one of more endorsements: | ||
+ | |||
+ | { | ||
+ | "status" : "invalid | unknown | unsuitable | approved", | ||
+ | "message" : "a message explaining why, if valid = false" | ||
+ | "endorsements": [{ | ||
+ | "endorser" : { | ||
+ | "name" : "displayable name for the endorser", | ||
+ | "url" : "Human usable URL for the endorser (e.g. a web reference)" | ||
+ | }, | ||
+ | "type" : "approval | warning | usage-note - could be used for an icon if displaying to a user", | ||
+ | "comment" : "text detail of note for human display" | ||
+ | }] | ||
+ | } | ||
+ | |||
+ | Status codes: | ||
+ | |||
+ | * invalid - the JWT itself is invalid - usually the signature could not be validated | ||
+ | * unknown - the JWT is correct and the signature is ok, but the application it identifies is not registered with the CAVS | ||
+ | * unsuitable - the application is registered, but the service deems that it should not be used (typically, it has been withdrawn due to security concerns) | ||
+ | * approved - the CAVS recommends that the application is ok to use, though there may be caveats in the endorsements | ||
− | + | Servers may choose to ignore the CAVS and only pass this information back to the user, though additional policy rules may be applied in this regard. | |
− | If, after considering the response from the | + | If, after considering the response from the CAVS, the EMR declines to honor the user's request, it responds to the $authorize operation with an error. Alternatively, the Source EHR may return endorsement information to the client on the $authorize response (as parameter "message") |
− | honor the user's request, it responds to the $authorize operation with | ||
− | an error. | ||
Notes | Notes | ||
− | * The degree to which a source EMR is required/allowed to verify the target EMR is an open policy question. This connectathon is not taking any policy position on this, only establishing infrastructure to support various possible policy positions | + | * The degree to which a source EMR is required/allowed to verify the target EMR (or the CCA in Scenario 3) is an open policy question. This connectathon is not taking any policy position on this, only establishing infrastructure to support various possible policy positions |
− | * validating the target EMR is an operation that can be carried out at any time, not just when the application is first authorized (see Revoking an API token below) | + | * validating the target EMR (or the CCA in Scenario 3) is an operation that can be carried out at any time, not just when the application is first authorized (see Revoking an API token below) |
− | * for this connectathon, no security is applied to this operation. Future iterations of the connectathon stream will consider security questions, and extensions to the | + | * for this connectathon, no security is applied to this operation. Future iterations of the connectathon stream will consider security questions, and extensions to the CAVS functionality described here |
==== Providing API token ==== | ==== Providing API token ==== | ||
− | Once | + | Once the target EHR has been authorized (or the CCA in Scenario 3), the patient client informs it by calling the $connect operation: |
− | POST [base]/$connect | + | POST [base]/$connect |
Inbound parameters: | Inbound parameters: | ||
− | * | + | * source : uri - the end-point URL for the Argonaut/S4S end-point of the application that it is authorised to acquire data from |
− | * | + | * consent : id: the resource id of the consent statement on the source system. Required read-only access, so the target knows what is authorized to access |
* duration : Duration - maximum length of time that authorization has been granted going to be honored | * duration : Duration - maximum length of time that authorization has been granted going to be honored | ||
* patient : id: the resource id of the patient on the target system that records are for (optional; default is the single patient associated with the authentication with the target application - it's an error if there's more than one) | * patient : id: the resource id of the patient on the target system that records are for (optional; default is the single patient associated with the authentication with the target application - it's an error if there's more than one) | ||
− | * | + | * jwt : string : the JWT that has been authorized (as originally provided by the target, but echoed back to the target) |
− | + | * authorization : String - the authorization token provided by the source EHR in response to the $authorize operation above. | |
− | * | ||
Response: 200 ok or an error with an operation outcome | Response: 200 ok or an error with an operation outcome | ||
Line 294: | Line 391: | ||
==== Acquiring Data from the Source EMR ==== | ==== Acquiring Data from the Source EMR ==== | ||
− | Once | + | Once a connection request has been received and accepted, the target EMR connects to the S4S interface identified in the $connect call, and calls it's token end-point (same end-point as defined in the Smart on FHIR login), but with slightly different parameters: |
− | + | POST [token-end-point] | |
− | + | Authorization: Bearer [jwt] | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | grant-type=client_credentials&authorization=[id] | |
− | + | where [jwt] is the JWT, and [id] is the authorization value, both from the $authorize operation | |
− | |||
− | The response is the standard SMART on FHIR access token response | + | The response is the standard SMART on FHIR access token response, which returns a token that can be used on the S4S interface |
Notes: | Notes: | ||
− | * the client (target EMR) does not specify any scopes in this case. Scopes are dictated by the consent resource | + | * the client (target EMR) does not specify any scopes in this case. Scopes are dictated by the consent resource, and are returned in the response, as is the patient in context |
* Searching on Patient on the source system using this API token will only match the Consent.patient, and only resources in that patient compartment are available | * Searching on Patient on the source system using this API token will only match the Consent.patient, and only resources in that patient compartment are available | ||
Line 323: | Line 414: | ||
Response 200 ok with parameters: | Response 200 ok with parameters: | ||
* token - tuple | * token - tuple | ||
− | ** app-id : url - previously authorized application (" | + | ** id : intenral id associated with the authorization |
− | ** | + | ** app-id : url - previously authorized application ("sub" header from the JWT) |
+ | ** expires : when the authorization expires | ||
** error : String - errors associated with this authorization (typically, the user make an authorization but the EMR is no longer prepared to honor it for some reason) | ** error : String - errors associated with this authorization (typically, the user make an authorization but the EMR is no longer prepared to honor it for some reason) | ||
Line 332: | Line 424: | ||
Inbound parameters: | Inbound parameters: | ||
− | * | + | * id : url - the internal id of the authorization |
− | |||
− | |||
− | |||
Response: 200 ok or an error with an operation outcome | Response: 200 ok or an error with an operation outcome | ||
Line 341: | Line 430: | ||
Note: any further use of tokens associated with this authorization will result in a 404 unauthorized response | Note: any further use of tokens associated with this authorization will result in a 404 unauthorized response | ||
− | === For pattern # | + | === For pattern #5/6 - Direct push === |
==== Starting push ==== | ==== Starting push ==== | ||
Line 410: | Line 499: | ||
When the system sends data by direct, it should use the profile as described by [[Sending FHIR resources in Direct Messages]]. Data is sent as collections, when ever the data is available, batched by sending system convenience. | When the system sends data by direct, it should use the profile as described by [[Sending FHIR resources in Direct Messages]]. Data is sent as collections, when ever the data is available, batched by sending system convenience. | ||
− | |||
− | |||
− | |||
Clients can find what push processes are set up for a given consent resource: | Clients can find what push processes are set up for a given consent resource: | ||
Line 421: | Line 507: | ||
* token - tuple | * token - tuple | ||
** address : uri - address data is being sent to | ** address : uri - address data is being sent to | ||
− | ** status : string - current status for human discussion - number of records sent, or current error message, as appropriate | + | ** status : string - current status for human discussion - number of records sent, or current error message, as appropriate |
− | Stopping | + | ==== Stopping push ==== |
POST [base]/Consent/[id]/$pushStop | POST [base]/Consent/[id]/$pushStop | ||
Line 436: | Line 522: | ||
== Relevant Specs, Documentation and Test Servers == | == Relevant Specs, Documentation and Test Servers == | ||
− | + | A collaborative working wiki has been set up at: [Pre-connectathon] (https://bitbucket.org/jeastman/consumer-centered-data-exchange/wiki/Home) | |
− | |||
* a specification for authorization, based on OAuth 2 (details at http://docs.smarthealthit.org/authorization/) | * a specification for authorization, based on OAuth 2 (details at http://docs.smarthealthit.org/authorization/) | ||
+ | *a Tutorial on building a Simple Authorization App (http://docs.smarthealthit.org/tutorials/authorization/) | ||
* a specification for data access, based on FHIR (details generally at http://docs.smarthealthit.org/ with details about data profiles at http://www.fhir.org/guides/argonaut/r2/) | * a specification for data access, based on FHIR (details generally at http://docs.smarthealthit.org/ with details about data profiles at http://www.fhir.org/guides/argonaut/r2/) | ||
* Publicly Available FHIR Servers for testing: (http://wiki.hl7.org/index.php?title=Publicly_Available_FHIR_Servers_for_testing) | * Publicly Available FHIR Servers for testing: (http://wiki.hl7.org/index.php?title=Publicly_Available_FHIR_Servers_for_testing) | ||
+ | * Open source FHIR Implmentations: (http://wiki.hl7.org/index.php?title=Open_Source_FHIR_implementations) | ||
+ | |||
+ | * [[201709 Consumer Centered Data Exchange Implementation Notes for test.fhir.org]] |
Latest revision as of 19:37, 10 September 2017
Consumer Centered Data Exchange
Submitting WG/Project/Implementer Group
FHIR Product Director, in association with Society for Participatory Medicine, MIHIN, NATE, DXC, Cerner (SoF Scenario only). Interested committees: FHIR-I, CBCC, Security, PA, PC, OO
Justification
In the connectathon process, we've tested narrow scenarios around data exchange, but interest is growing quickly to increase understanding of Consumer Centered Directed Exchange.
Consumer Centered Data Exchange can be thought of as a category of use cases including:
- Consumer Access (CA) - in these use cases data held by a Source EMR is transferred to a Consumer Controlled App (CCA).
- Consumer Initiated Exchange (CIE) - in these use cases the actions of a Consumer result in the transfer of data from a Source EMR to a Target EMR (via Consent or otherwise where the data is exchange amongst Covered Entities at the Direction of the Consumer and is not TPO)
- Consumer Directed Exchange (CDE) - in these use cases data held by a CCA is transferred to a Target EMR
The justification for this track is to develop an understanding of what - if anything - the main specification of the US core IG should say about enabling these consumer-centric use case.
Proposed Track Lead
Grahame Grieve (mentoring Aaron Seib to take over after this)
Summary
Presentation from wrap-up:
Zulip stream
For discussion purposes, the following thread should be used on the FHIR Chat
Expected participants
- NATE
- MIHIN
- HSS IDEA Lab Authors of the POET specification Mark Scrimshire & Alan Viars
- http://test.fhir.org/r3
- Cerner (for SoF scenarios only)
- EMR Direct
- DXC
- CareEvolution
- GetRealHealth
- Humetrix
- MedFusion
- John Moehrke (HL7 Security co-chair) SME on FHIR Consent
(others: email aaron.seib@nate-trust.org if you are interested in getting involved)
Scenario
Paul is a VA beneficiary living in Alaska. Because of the remoteness of his location, there aren’t a lot of specialists at his local VA facility for him to see and as a result Paul frequently gets referred to local civilian specialists outside of the VA. Following specialist visit(s) Paul would like to ensure that the PHI generated by the specialist as a result of the encounter is shared with his providers at the VA. Thus, there is a need to transfer information from the specialist to the VA record that his VA Providers access.
Paul uses a Consumer Controlled Application (CCA) where he is able to maintain records from all of his providers in one place.
Paul would like to cause relevant EMR data to be transferred from the specialist's system (the Source EMR) to the VA's EMR (the Target EMR).
The scenarios being proposed in this track describe several methods that may enable Paul "to cause" this transfer.
Assumptions: we intended to reuse and extend as necessary existing capabilities developed to date by the FHIR-community including:
- the Argonaut interface - leverage the ability to access data from an EMR that is provided by an Argonaut based patient portals;
- SMART-on-FHIR;
- Various FHIR resources such as the Consent resource; and
- Others as identified.
See Relevant Specs and Documentation below.
Roles
- Consumer Controlled App: the CCA of Paul's choice
- Source EMR system: the Specialist EMR that will make the data available
- Target EMR system: the VA or equivalent system that will acquire the data
- Consumer App Verification Service: a service that verifies 'Claim(s)' made by an App for a relying party when a use case performs "Application Verification"
- eConsent Management System: a service performed by an HIN that acts as a relay to end-points
Authorization pattern
There are 8 possible patterns for Authorizing/Managing the data flow
- 1. Provider to Provider via SMART on FHIR Consumer Initiated Exchange (P2P via SoF CIE)
- 2. Provider to Provider via SMART on FHIR Consumer Initiated Exchange with Consent (P2P via SoF CIE with Consent)
- 3. Provider to Consumer via SMART on FHIR Consumer Access (P2C via SoF CA)
- 4. Consumer to Provider via SMART on FHIR Consumer Directed Exchange (C2P via SoF CDE)
- 5. Provider to Provider via Direct Secure Messaging with Consent (P2P via DSM with Consent CIE)
- 6. Provider to Consumer via Direct Secure Messaging with Individual Right of Access request (P2C via DSM with IRA CA)
- 7. Full UMA
- 8. P2P via HIN with eConsent Management Service
1. P2P via SoF CIE
Data is made available to a target EMR by the normal SMART on FHIR interface (see http://docs.smarthealthit.org/authorization/). In this scenario:
- Paul logs into the target EMR app (EHR launch via the EMR's Patient Portal), and informs the app that he wants to connect it to the source EMR (how this is done is outside the scope of the connectathon)
- The target EMR app (re)directs Paul to the authorization URL on the source EMR
- Paul authorizes the application as he wants
- the target EMR makes requests of the source system in an ongoing fashion per SMART on FHIR
- Paul connects to the source EMR to revoke his authorization when he wants the data flow to end
This scenario requires Paul to know the URLs for both source EMR and the target EMR, he must deal with multiple applications, and is dependent on Trust Already Existing between the Source and Target EMR.
Notes:
- there is no new API/interface in this arrangement - all of this is as described today, with additional application work.
- this is actually more complicated than a simpler alternative: Paul has an application that downloads content from the source, and uploads it to the target. This approach has 2 problems - there's no trust (provenance) associated with the target/source connection (and there's plenty of real world demonstration that this is a big problem for care providers) and flow of data depends on Paul's devices and connectivity. There is solid grounds for Paul being able to download/update data from/to EMRs, but this connectathon stream focuses on giving the customer control over direct data flow
Assumptions for this Connectathon:
- The target EMR is registered with the source EMR before the scenario begins.
- The source EMR's Conformance Statement is known to the target EMR.
- The source EMR provides Paul a method to revoke his authorization.
2. P2P via SoF CIE with Consent
Similar to scenario 1 -
Data is made available to a target EMR by the normal SMART on FHIR interface with a consent layer.
In this scenario:
- Paul authorizes an app to the source EMR (http://docs.smarthealthit.org/authorization/)
- Paul posts a Consent resource to the server, or chooses an existing consent statement.
- Paul asks the target server for it's identifying token (see 'Acquiring an Applications JWT' below)
- Paul asks the source server for an access token for the target server based on the consent (see 'Authorizing an Application' below)
- Paul authorizes with the target server, and gives it the API token (see 'Providing API token' below)
- the target EMR makes requests of the source system in an ongoing fashion using the API token
- Paul can revoke the authorize by revoking the token (see 'Revoking an API token' below)
This scenario requires Paul to know the URLs for both source and target, and to have apps authorized to both of them (could be the same app) but he doesn't have to deal with multiple applications, and trust relationships between them are not required.
3. Provider to Consumer via SoF Consumer Access
Similar to Scenario 1 except in the place of a Target EMR, Paul is requesting Data be sent to his CCA
Data is made available to the CCA by the normal SMART on FHIR interface (see http://docs.smarthealthit.org/authorization/).
In this scenario:
- Paul logs into the CCA and informs the app that he wants to connect it to the source EMR (how this is done is to be explored as part of the connectathon).
- The source EMR may perform Application Validation to verify that the CCA has sufficient endorsements per local policy to support this use case.
- The CCA (re)directs Paul to the authorization URL on the source EMR.
- Paul authorizes the application as he wants.
- the CCA makes requests of the source system in an ongoing fashion per SMART on FHIR.
- Paul connects to the source EMR to revoke his authorization when he wants the data flow to end.
This scenario requires Paul to know the URLs for the source EMR and to have an account with a FHIR-enabled CCA. Dynamic App registration is out of scope for this connectathon meaning that the CCA must be registered to the source EMR prior to the start of the scenario. Paul must deal with multiple applications, and is dependent on trust already existing between the Source and the CCA. The Source EMR may perform Consumer Application Verification periodically on the CCA in question by following the Application Verification process.
4. Consumer to Provider via SoF Consumer Directed Exchange
This scenario is similar to scenario 2 except instead of data flowing from the Source EMR to the Target EMR (Institution to institution) a Consumer Controlled Health App is the Source. With the Consumer directing the flow of data a consent layer is not required but to support the Target EMR’s trust in the Consumer App we invoke Application Verification when the target EMR may wish to verify that the Consumer App identified in the $authorize operation is acceptable to it. To do this, the target EMR can take the public key provided in the "publicKey" parameter of the $authorize operation, and send it to a 3rd party Consumer Application Verification Service (CAVS) that it trusts to provide advice similar to the interactions between a Source and Target EMR in scenario 2.
- Paul authorizes his consumer controlled app (CCA) to release selected content to a target EMR
- Paul asks the target server for it's identifying token (see 'Acquiring an Applications JWT' below)
- Paul asks the source server for an access token for the target server based on the consent (see 'Authorizing an Application' below)
- Paul gives the target server the API token (see 'Providing API token' below) and the “publicKey” of the CCA
- The target EMR invokes Application Verification using the “publickey” and a local policy engine to determine if it “trust” the Consumer App for this use case.
- The target EMR makes requests of the CCA (which implies to me that this could be discovered via the same registry as the one used to check for endorsements) for the content using the API token.
This scenario requires Paul’s CCA to know the target EMR’s URL for this use case (CDE). This scenario also requires the target EMR to know the location of the 3rd party server that Paul’s CCA is registered with to retrieve the endorsements associated with that CCA for evaluation by the target EMR’s local policy engine. In this scenario a precondition is that the Consumer Controlled App has content that the consumer wishes to share with the target EMR.
5. P2P via DSM with Consent
In this scenario, data is made available in the same format as Argonaut, but instead of a Pull based API, a push using Direct is used instead.
In this scenario:
- Paul authorizes a target EMR to the source EMR (standard SMART on FHIR)
- Paul posts a Consent resource to the server, or chooses an existing consent statement
- Paul asks the source EMR to start pushing the data based on the consent (see 'Starting push' below)
- the source EMR sends data to the target EMR using direct based push
- Paul can stop the sending through the source EMR (see 'Stopping push' below)
This scenario requires Paul to know the URLs for the source, and the right direct email address for the target, and direct support must exist for the transfer between source and target. Paul doesn't have to have any relationship with the target, deal with multiple applications, and trust relationships between them are not required
6. P2C via DSM with IRA request
In this scenario, data is made available in the same format as Argonaut, but instead of a Pull based API, a push using Direct is used.
In this scenario:
- Paul authorizes his CCA to the source EMR (standard SMART on FHIR)
- Paul posts an Individual Right of Access request (profile of a Consent Resource) to the server
- Paul asks the source EMR to start pushing the data based on the consent (see 'Starting push' below)
- the source EMR sends data to the his CCA using direct based push
- Paul can stop the sending through the source EMR (see 'Stopping push' below)
NOTE:
This scenario creates an opportunity to explore how a Consumer's Direct Address could be "passed" to an EMR to be used in subsequent "Pushes". It relies on the SoF mechanism to enable the posting of an IRA to the source EMR. It would require the source EMR to implement a process to "start" and "stop" the sending of Content.
7. Full UMA
Data is made available by the normal Argonaut interface, but the authorization has been delegated to a central server that manages the patient Authorization per the HEART/UMA specification.
- Paul grants target EMR (the VA) access to his data through the UMA Authorization Server's grant management interface
- Target EMR initiates UMA-based authorization by requesting access to Paul's protected data on the source EMR
- Source EMR contacts AS to obtain an UMA permission ticket, then returns a 403 Unauthorized response to the target EMR containing this permission ticket and the URL for the AS
- Target EMR asks the AS to exchange the permission ticket for a requesting party token (RPT)
- AS authenticates target EMR and issues RPT to target EMR
- Target EMR uses RPT as bearer token to access the protected data from the source EMR in an ongoing fashion
- Paul can revoke target EMR's access through AS grant management interface
Note: this builds on the Argonaut interface by adding HEART/UMA support to it. This scenario requires the target EMR to know the source EMR’s FHIR URL, but knowledge of the UMA AS URL is not required. The source EMR has previously delegated authorization to Paul's data (resource set) to the UMA-enabled AS and the AS is able to authenticate the target EMR.
8. P2P via HIN with eConsent Management Service
In this scenario a veteran is admitted to a non-VA substance use disorder treatment facility that receives federal funding and is thus subject to 42 CFR 2 requiring written patient consent for the facility to share SUD-related information (including the fact of admission) with “name recipients” from the patient’s consent form.
To facilitate this scenario a simulated Health Information Network operating an electronic Consent Management Service (eCMS) facilitates sharing with the consumer’s Care Team with the consumer’s consent.
The scenario participant is able to create a consent for a consumer Persona (synthetic patient). Complete Persona information will be provided for each scenario participant. Each scenario participant will enter basic demographic information from the Persona data into a (provided) “Consumer Portal” (which is embeddable) and will use this to create an electronic consent which is then automatically sent to the HIN and stored in the eCMS based on the demographic information on the consent form which the HIN uses to match the patient to a list of authorized recipient derived from the “metadata” in the electronic CMS taken from the electronic consent form in the portal.
The 42 CFR 2 SUD treatment facility now wishes to send the “Admission Discharge Transfer” (ADT) notification (provided to scenario participants in HL7 v2 test data / pipe delimited text) with the HIN so the HIN can broadcast this ADT notification to all named recipients from the patient consent form. Source EMRs are able to check if there is a consent on file for for their consumer Persona by querying the eCMS (using FHIR). If there is a valid consent on file for that consumer in the query, the eCMS notifies the source EMR and the source EMR is able to insert privacy tags in content (an ADT – test data is provided) and send content (the ADT with test data) to the HIN which then uses information from the eCMS to distribute the data to authorized end users (e.g. the consumer’s named recipients).
In this scenario:
• The consumer (e.g. the scenario participant) fills in the standard electronic consent form on the (embeddable) consumer portal page which then posts both a Contract resource and a Consent resource to the eCMS server.
• This consent, if valid, authorizes the sEMR to share data with the HIN (which subsequently distributes the data to the authorized end-points)
• A source EMR wants to send an ADT to the authorized end-points associated with their consumer Persona in the eCMS. • The source EMR queries the eCMS to find out if there is a consent for their consumer Persona.
• If there is no matching consent in the eCMS the source EMR does nothing further.
• If there is a matching consent in the eCMS then the source EMR (a) first inserts a “privacy tag” (the letters “SPI”) into the “security label” field of the HL7 v2 ADT and then (b) sends the (test) ADT containing the privacy tag to the HIN (simulated) which then queries the eCMS to determine “named recipients” from the electronic consumer’s consent form and finally broadcasts the (test) ADT to the authorized end points (simulated) for those named recipients (in accordance with SAMHSA 42 CFR 2).
• When the HIN receives an ADT it first checks to see if a privacy tag is contained in it and if so, the HIN matches the patient to the consent metadata stored in the eCMS to retrieve a list of authorized end-user electronic end-points and then the HIN distributes the ADT to the consumer’s named recipients in conformance with the Consent.
• The consumer Persona (scenario participant) can revoke the consent that is posted to the eCMS server at any time.
Interfaces
For pattern #2 - Provider to Provider with Consent CCDE
4 parties:
- patient : orchestrates the connection, connected to 2 different EHRs
- target EHR: will be asked to pull data from the source EHR using it's argonaut interface
- source EMR: will be authorised to provide data to the source EHR on behalf of the patient
- Application Endorser: source ER may use this to verify how much it trusts the target
note: identification of the target EHR is based on a JWT. The JWT should include a "sub" that names the target EHR. It may also include an expiry date. The JWT must be signed. The suitability of a JWT is open to debate - JWK and/or a simple public key are alternatives with different pros and cons.
Authorizing an Application
Call this on on the source EHR:
POST [base]/Consent/[id]/$authorize
Inbound Parameters:
- jwt : string - a JWT that identifies the target EHR (see below for how to get that)
- duration : Duration - how long the token should be good for. (optional: default to Consent.period if not provided) (cannot be be for longer than the consent itself, or the expiry in the JWT)
Response: 200 ok with Parameters, or an error with an operation outcome. Outbound Parameters:
- duration : Duration - maximum length of time that the token is going to be honored. No duration means that the approval is not time limited
- authorization : a token that identifies the authorization - used later by the target EHR
The source EHR returns an error if it is not able to understand the consent resource fully, or if it is not prepared to honor the consent statement (e.g. it probably won't agree to a consent that grants more than the granting application itself has been authorized to have), or if it refuses to authorize the specified application for some reason (see below for further discussion on the implementation and policy of this). The source EHR should verify the signature on the JWT, and may choose to verify the client (see below)
The user of the client - usually, but not necessarily - a human - chooses the Consent on which to base $authorise the target EHR. Note that the only system that computes with this consent is the source EHR, which provides the consent itself; no other system needs to compute with the consent (the patient's software just has to let the patient choose a consent). Note: the source EHR may let the patient provide the consent through the client - that is a different transaction that is out of scope for this connectathon
If a computable consent is required, this is the suggested template:
<Consent xmlns="http://hl7.org/fhir"> <id value="[id from api]"/> <text> // as appropriate // </text> <status value="active"/> // can only perform $getToken on active consent statements // <patient>// patient data to be shared //</patient> <period>// optional period //</period> <dateTime value="[optional]"/> <actor> // text/code description of who's going to be granted access. This is useful for describing the recipient, but won't have any computed meaning // </actor> <organization>// good to fill this out for consumption, but not important //</organization> <policyRule value="http://hl7.org/fhir/ConsentDefinition/simple-oauth"> <purpose> // optional but not processed //</purpose> <dataPeriod>// optional, enforced if present //</dataPeriod> // don't use this // <except> // the definition of http://hl7.org/fhir/ConsentDefinition/simple-oauth is that only this consent statement is granted access. Anything else is granted access by exception // <type value="permit"/> // not used <period/>, <actor/> // <action> // this consent grants the right to access data // <coding> <system value="http://hl7.org/fhir/consentaction"/></coding> </action> // not used <securityLabel/>, <purpose/> // // repeat class for each Smart on FHIR scope // <class> <system value="http://smarthealthit.org/fhir/scopes"/>
</class> // not used
, <dataPeriod/>, // </except> </Consent>
Note: This profile is a restricted form of the Consent resource that allows the user to consent using Smart on FHIR scopes
Acquiring an Applications JWT
The operation above requires that the client have a JWT that identifies the target EHR. This is done by calling [base]/$jwt?source=[url] on the target EHR, where source is the S4S endpoint from the source EHR. The target EHR returns a body of type application/jwt that contains the JWT that the target wishes to use to identify itself to the source EHR. Note that source is a mandatory parameter, but it is up to the target EHR whether to use it's standard JWT or to make up a single use JWT.
Application Verification
The source EMR may wish to verify that the target EMR (or the CCA in Scenario 3) identified in the $authorize operation is acceptable to it. it can perform this operation either when $authorize is called, or when the target EHR connects to it (see below).
To do this, the source EMR can take the jwt provided in the "jwt" parameter of the $authorize operation, and send it to Client App Validation service that provides information about what endorsements are verifiably attributed to the target EMR (or CCA as the case may be).
POST [base] Content-Type: application/x-www-form-urlencoded
jwt=[jwt]
where [base] is the URL of the CAVS (client application verification service). The CAVS will return a json object listing one of more endorsements:
{ "status" : "invalid | unknown | unsuitable | approved", "message" : "a message explaining why, if valid = false" "endorsements": [{ "endorser" : { "name" : "displayable name for the endorser", "url" : "Human usable URL for the endorser (e.g. a web reference)" }, "type" : "approval | warning | usage-note - could be used for an icon if displaying to a user", "comment" : "text detail of note for human display" }] }
Status codes:
- invalid - the JWT itself is invalid - usually the signature could not be validated
- unknown - the JWT is correct and the signature is ok, but the application it identifies is not registered with the CAVS
- unsuitable - the application is registered, but the service deems that it should not be used (typically, it has been withdrawn due to security concerns)
- approved - the CAVS recommends that the application is ok to use, though there may be caveats in the endorsements
Servers may choose to ignore the CAVS and only pass this information back to the user, though additional policy rules may be applied in this regard.
If, after considering the response from the CAVS, the EMR declines to honor the user's request, it responds to the $authorize operation with an error. Alternatively, the Source EHR may return endorsement information to the client on the $authorize response (as parameter "message")
Notes
- The degree to which a source EMR is required/allowed to verify the target EMR (or the CCA in Scenario 3) is an open policy question. This connectathon is not taking any policy position on this, only establishing infrastructure to support various possible policy positions
- validating the target EMR (or the CCA in Scenario 3) is an operation that can be carried out at any time, not just when the application is first authorized (see Revoking an API token below)
- for this connectathon, no security is applied to this operation. Future iterations of the connectathon stream will consider security questions, and extensions to the CAVS functionality described here
Providing API token
Once the target EHR has been authorized (or the CCA in Scenario 3), the patient client informs it by calling the $connect operation:
POST [base]/$connect
Inbound parameters:
- source : uri - the end-point URL for the Argonaut/S4S end-point of the application that it is authorised to acquire data from
- consent : id: the resource id of the consent statement on the source system. Required read-only access, so the target knows what is authorized to access
- duration : Duration - maximum length of time that authorization has been granted going to be honored
- patient : id: the resource id of the patient on the target system that records are for (optional; default is the single patient associated with the authentication with the target application - it's an error if there's more than one)
- jwt : string : the JWT that has been authorized (as originally provided by the target, but echoed back to the target)
- authorization : String - the authorization token provided by the source EHR in response to the $authorize operation above.
Response: 200 ok or an error with an operation outcome
Acquiring Data from the Source EMR
Once a connection request has been received and accepted, the target EMR connects to the S4S interface identified in the $connect call, and calls it's token end-point (same end-point as defined in the Smart on FHIR login), but with slightly different parameters:
POST [token-end-point] Authorization: Bearer [jwt]
grant-type=client_credentials&authorization=[id]
where [jwt] is the JWT, and [id] is the authorization value, both from the $authorize operation
The response is the standard SMART on FHIR access token response, which returns a token that can be used on the S4S interface
Notes:
- the client (target EMR) does not specify any scopes in this case. Scopes are dictated by the consent resource, and are returned in the response, as is the patient in context
- Searching on Patient on the source system using this API token will only match the Consent.patient, and only resources in that patient compartment are available
Revoking an API token
getting a list of tokens:
GET [base]/Consent/[id]/$authorizations
Response 200 ok with parameters:
- token - tuple
- id : intenral id associated with the authorization
- app-id : url - previously authorized application ("sub" header from the JWT)
- expires : when the authorization expires
- error : String - errors associated with this authorization (typically, the user make an authorization but the EMR is no longer prepared to honor it for some reason)
Revoking a Token:
POST [base]/Consent/[id]/$revokeAuthorization
Inbound parameters:
- id : url - the internal id of the authorization
Response: 200 ok or an error with an operation outcome
Note: any further use of tokens associated with this authorization will result in a 404 unauthorized response
For pattern #5/6 - Direct push
Starting push
POST [base]/Consent/[id]/$pushStart
Inbound Parameters:
- duration : Duration - how long the application should push data for. (optional: default is system should push data until otherwise instructed)
- address : uri - direct address (email address) where the data should be sent
Response: 200 ok with Parameters, or an error with an operation outcome. Outbound Parameters:
- address : uri - where the data is going to be sent
- duration : Duration - maximum length of time that the token is going to be honored. If this is missing, the source will send until otherwise installed
The server returns an error if it is not able to understand the consent resource fully, or if it is not prepared to honor the consent statement (e.g. it may not agree to a consent that grants more than the granting application itself has been authorized to have). The server may also return an error if it cannot or will not send to the nominated direct address
For the purposes of this connectathon, this is the suggested profile on the Consent Statement:
<Consent xmlns="http://hl7.org/fhir"> <id value="[id from api]"/> <text> // as appropriate // </text> <status value="active"/> // can only perform $getToken on active consent statements // <patient>// patient data to be shared //</patient> <period>// optional period //</period> <dateTime value="[optional]"/> <actor> // text/code description of who's going to be granted access. This is useful for describing the recipient, but won't have any computed meaning // </actor> <organization>// good to fill this out for consumption, but not important //</organization> <policyRule value="http://hl7.org/fhir/ConsentDefinition/simple-oauth"> <purpose> // optional but not processed //</purpose> <dataPeriod>// optional, enforced if present //</dataPeriod> // don't use this // <except> // the definition of http://hl7.org/fhir/ConsentDefinition/simple-oauth is that only this consent statement is granted access. Anything else is granted access by exception // <type value="permit"/> // not used <period/>, <actor/> // <action> // this consent grants the right to access data // <coding> <system value="http://hl7.org/fhir/consentaction"/></coding> </action> // not used <securityLabel/>, <purpose/> // // repeat class for each Smart on FHIR scope // <class> <system value="http://smarthealthit.org/fhir/scopes"/>
</class> // not used
, <dataPeriod/>, // </except> </Consent>
Notes:
- This profile is a restricted form of the Consent resource that allows the user to consent using Smart on FHIR scopes
- Systems that don't allow upload of consent, but allow $pushRecords, can do whatever consent they can understand - the client does not need to understand the consent details to call $pushRecords.
- this API is also controlled by the FHIR scope "Consent/flow" that a client can ask for to indicate that it wishes to use the Push API control described here in addition to read and/or write of Consent resources
When the system sends data by direct, it should use the profile as described by Sending FHIR resources in Direct Messages. Data is sent as collections, when ever the data is available, batched by sending system convenience.
Clients can find what push processes are set up for a given consent resource:
GET [base]/Consent/[id]/$listPush
Response 200 ok with parameters:
- token - tuple
- address : uri - address data is being sent to
- status : string - current status for human discussion - number of records sent, or current error message, as appropriate
Stopping push
POST [base]/Consent/[id]/$pushStop
Inbound parameters:
- address : uri - Direct address to stop sending to
Response: 200 ok or an error with an operation outcome
Data will stop flowing once a 200 is returned
Relevant Specs, Documentation and Test Servers
A collaborative working wiki has been set up at: [Pre-connectathon] (https://bitbucket.org/jeastman/consumer-centered-data-exchange/wiki/Home)
- a specification for authorization, based on OAuth 2 (details at http://docs.smarthealthit.org/authorization/)
- a Tutorial on building a Simple Authorization App (http://docs.smarthealthit.org/tutorials/authorization/)
- a specification for data access, based on FHIR (details generally at http://docs.smarthealthit.org/ with details about data profiles at http://www.fhir.org/guides/argonaut/r2/)
- Publicly Available FHIR Servers for testing: (http://wiki.hl7.org/index.php?title=Publicly_Available_FHIR_Servers_for_testing)
- Open source FHIR Implmentations: (http://wiki.hl7.org/index.php?title=Open_Source_FHIR_implementations)