You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page serves as best practice guidance for CDS Hooks implementers. The best practices outlined here are not mandatory implementation rules; rather, they are suggested guidance. This is a living, in progress document and the best practices outlined here should not be considered absolute or complete.
4
+
5
+
## Security
6
+
7
+
The CDS Hooks security model requires thought and consideration from implementers. Security topics are never binary, are often complex, and robust implementations should factor in concepts such as risk and usability. Implementers should approach their security related development with thoughtful care.
8
+
9
+
The CDS Hooks specifications already provides some guidance in this space. The information here is supplemental to the existing specification documentation.
10
+
11
+
The CDS Hooks security model leverages several existing RFCs. These should be read and fully understood by all implementers.
12
+
13
+
-[rfc7519: JSON Web Tokens (JWT)](https://tools.ietf.org/html/rfc7519)
14
+
-[rfc7517: JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517)
15
+
-[rfc7515: JSON Web Signature (JWS)](https://tools.ietf.org/html/rfc7515)
16
+
-[rfc7518: JSON Web Algorithms (JWA)](https://tools.ietf.org/html/rfc7518)
17
+
18
+
### CDS Clients
19
+
20
+
Implementers of CDS Clients should:
21
+
22
+
**Maintain a whitelist of CDS Service endpoints that may be invoked.**
23
+
24
+
Only endpoints on the whitelist can be invoked. This ensures that CDS Clients invoke only trusted CDS Services. This is especially important since CDS Clients may send an authorization token that allows the CDS Service temporary access to the FHIR server.
25
+
26
+
**Issue secure FHIR access tokens.**
27
+
28
+
*If* a CDS Clients generates access tokens to its FHIR server, the tokens should:
29
+
30
+
- Be unique for each CDS Service endpoint.
31
+
- Be very short-lived.
32
+
- Provide the minimum necessary access for the CDS Service. This includes both SMART scopes as well as the patient(s)/data that can be accessed.
33
+
34
+
### CDS Services
35
+
36
+
#### JWT
37
+
38
+
Upon being invoked by a CDS Client, the CDS Service should first process the given JWT to determine whether to process the given request. In processing the JWT, CDS Services should:
39
+
40
+
1. Ensure that the `iss` value exists in the CDS Service's whitelist of trusted CDS Clients.
41
+
2. Ensure that the `aud` value matches the CDS Service endpoint currently processing the request.
42
+
3. Ensure that the `exp` value is not before the current date/time.
43
+
4. Ensure that the `tenant` value exists in the CDS Service's whitelist of trusted tenants (may not be applicable to all CDS Services).
44
+
5. Ensure that the JWT signature matches the public key on record with the CDS Service. See additional notes below.
45
+
6. Ensure that the `jti` value doesn't exist in the short-term storage of JWTs previously processed by this CDS Service.
46
+
47
+
Once the JWT has been deemed to be valid, the `jti` value should be stored in the short-term storage of processed JWTs. Values in this storage only need to be kept for the maximum duration of all JWTs processed by this CDS Service. If the CDS Clients are adhering to best practices, this should be no more than an hour.
48
+
49
+
Verifying the JWT signature is a critical step in establishing trust of the caller of the CDS Service. As part of the whitelist of trusted CDS Clients, information on the public key(s) used by the CDS Client should also be stored. In some cases, this public key may be shared out-of-band. In other cases, the public key may be available at a remote endpoint and cycled on a regular basis. It is this latter case in which CDS Services should maintain their own rotating cache of public keys for the CDS Client.
50
+
51
+
CDS Services should never store, share, or log JWTs to minimize the risk of theft and replay attacks. Information within the JWT (for instance, `iss`, `tenant`, `jti`) can be logged safely and is especially useful for analytics.
52
+
53
+
If a CDS Service deems a JWT to be invalid for any reason, it should not leak the details of why the JWT failed validation back to the caller. If the caller were a malicious threat actor, leaking detailed information as to what was invalid may give the threat actor guidance on how to shape future attacks. Instead, responding to the request with a HTTP 401 Unauthorized response status code without any additional information is recommended.
54
+
55
+
#### FHIR Access
56
+
57
+
CDS Services should never store, share, or log the FHIR access token (`fhirAuthorization.access_token`) given to it by the CDS Client. The access token should be treated as an extremely sensitive, transient piece of data.
Copy file name to clipboardExpand all lines: docs/index.md
+10-6Lines changed: 10 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
This specification describes a
4
4
["hook"](http://en.wikipedia.org/wiki/Hooking)-based pattern for invoking
5
-
decision support from within a clinician's EHR workflow. The API supports:
5
+
decision support from within a clinician's workflow. The API supports:
6
6
7
7
* Synchronous, workflow-triggered CDS calls returning information and suggestions
8
8
* Launching a user-facing SMART app when CDS requires additional interaction
@@ -12,13 +12,13 @@ decision support from within a clinician's EHR workflow. The API supports:
12
12
13
13
## How it works
14
14
15
-
User activity inside the EHR triggers **CDS hooks** in real-time. For example:
15
+
User activity inside the clinician's workflow triggers **CDS hooks** in real-time. For example:
16
16
17
17
*`patient-view` when opening a new patient record
18
18
*`medication-prescribe` on authoring a new prescription
19
19
*`order-review` on viewing pending orders for approval
20
20
21
-
When a triggering activity occurs, the EHR notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the EHR
21
+
When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow
22
22
context (via the `context` parameter of the hook) plus whatever
23
23
service-specific data are required (via the `pre-fetch-template` parameter).
24
24
@@ -30,14 +30,18 @@ Each CDS service can return any number of **cards** in response to the hook.
30
30
Cards convey some combination of text (*information card*), alternative
31
31
suggestions (*suggestion card*), and links to apps or reference
32
32
materials (*app link card*). A user sees these cards — one or more of each type
33
-
— embedded in the EHR, and can interact with them as follows:
33
+
— embedded in the workflow, and can interact with them as follows:
34
34
35
35
**information card*: provides text for the user to read.
36
36
37
-
**suggestion card*: provides a specific suggestion for which the EHR renders a button that the user can click to accept. Clicking automatically populates the suggested change into the EHR's UI.
37
+
**suggestion card*: provides a specific suggestion for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician's UI.
38
38
39
39
**app link card*: provides a link to an app (often a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision.
40
40
41
41
## Try it!
42
42
43
-
You can try CDS Hooks in our Sandbox at **[http://sandbox.cds-hooks.org](http://sandbox.cds-hooks.org)**
43
+
You can try CDS Hooks in our Sandbox at [http://sandbox.cds-hooks.org](http://sandbox.cds-hooks.org)
44
+
45
+
An [OpenAPI Specification](https://www.openapis.org/) (formally known as the Swagger Specification) interface of CDS Hooks is available. Using the CDS Hooks OpenAPI specification, you can generate client or server code to help you get started with your implementation. You can download the [API specification](https://github.com/cds-hooks/api) and view it online via the [Swagger Editor](http://editor.swagger.io/?url=https://raw.githubusercontent.com/cds-hooks/api/master/cds-hooks.yaml).
46
+
47
+
CDS Hooks implementers are not required to use the OpenAPI Specification interface of CDS Hooks.
Copy file name to clipboardExpand all lines: docs/quickstart.md
+12-12Lines changed: 12 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,23 @@
1
1
# Quick Start
2
2
This quick start tutorial defines each of the actors and provides details for implementing the `patient-view` hook.
3
3
4
-
A CDS Hooks scenario typically includes two main actors: an EHR and a CDS Service. Below is an example interaction for the `patient-view` hook.
4
+
A CDS Hooks scenario typically includes two main actors: an CDS Client and a CDS Service, where the CDS Client may be an EHR, CPOE or other clinical workflow system. Below is an example interaction for the `patient-view` hook.
A CDS Service is an external service that responds to EHR requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service:
9
+
A CDS Service is an external service that responds to CDS Client requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service:
10
10
11
11
1. Create an endpoint for discovery
12
12
2. Develop a service
13
13
3. Test the service with the [sandbox](http://sandbox.cds-hooks.org/)
14
14
4. If applicable, create a SMART app (or [borrow one](https://apps.smarthealthit.org/apps/pricing/open-source))
15
-
5. Test the service (and, if applicable, SMART app) with an EHR
15
+
5. Test the service (and, if applicable, SMART app) with an CDS Client
16
16
17
17
This tutorial recommends implementing the CDS Hooks [security model](specification/1.0/#security-and-safety) after successful open access testing.
18
18
19
19
### Endpoint for discovery
20
-
The CDS Service must provide a stable endpoint for the EHR to discover the available services. A system must expose their services at `{baseUrl}/cds-services`. A service endpoint that supports the `patient-view` hook may return:
20
+
The CDS Service must provide a stable endpoint for the CDS Client to discover the available services. A system must expose their services at `{baseUrl}/cds-services`. A service endpoint that supports the `patient-view` hook may return:
21
21
22
22
```json
23
23
{
@@ -78,9 +78,9 @@ Select the configure hooks:<br>
78
78
Delete the existing hooks, and then do a quick add with a reference to your CDS Service:<br>
79
79
80
80
81
-
After testing with the sandbox, you are ready to connect with an EHR service.
81
+
After testing with the sandbox, you are ready to connect with an CDS Client.
82
82
83
-
## Integrating CDS Services into an EHR
83
+
## Integrating CDS Services into a CDS Client
84
84
Build out following sections:
85
85
86
86
1. Call discovery endpoint
@@ -94,7 +94,7 @@ Build out following sections:
94
94
This tutorial recommends implementing the CDS Hooks [security model](specification/1.0/#security-and-safety) after successful open access testing.
95
95
96
96
### Call discovery endpoint
97
-
The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. An EHR may configure their system to support a set of hooks at a certain location in their users work flow, or build a dynamic capability to interact with a CDS Service provider within a work flow. For the best end-user experience, this guide recommends a business analyst configure which hooks an EHR will support.
97
+
The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. A CDS Client may configure their system to support a set of hooks at a certain location in their users work flow, or build a dynamic capability to interact with a CDS Service provider within a work flow. For the best end-user experience, this guide recommends a business analyst configure which hooks a CDS Client will support.
98
98
99
99
Below is an example work flow where a business analyst accesses this list of available services by calling
100
100
@@ -107,10 +107,10 @@ and then configures them in the system.
107
107
This image captures a business analyst reviewing services from one CDS provider. A business analyst may review services from multiple providers and configure appropriate services per user profiles.
108
108
109
109
### Invoke service on patient-view hook
110
-
The `patient-view` hook is invoked when a patient chart is opened. It's one of the most basic since the logic doesn't have any prior workflow dependencies. The service called on the `patient-view` hook could be dependent on patient characteristics, for example: sex, problems in problems list, active medications, etc. The current version of the CDS Hooks specification allows the EHR to decide which characteristics to consider.
110
+
The `patient-view` hook is invoked when a patient chart is opened. It's one of the most basic since the logic doesn't have any prior workflow dependencies. The service called on the `patient-view` hook could be dependent on patient characteristics, for example: sex, problems in problems list, active medications, etc. The current version of the CDS Hooks specification allows the CDS Client to decide which characteristics to consider.
111
111
112
112
### Support FHIR resource on CDS requests (context or pre-fetch)
113
-
Often a CDS Service will require additional information from the EHR to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the EHR the capability to pass a resource when invoking a service. For example, with a patient resource included a service could do a geography search for potential environmental risk factors. Below is an example request invoked on patient-view with a patient included:
113
+
Often a CDS Service will require additional information from the CDS Client to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the CDS Client the capability to pass a resource when invoking a service. For example, with a patient resource included a service could do a geography search for potential environmental risk factors. Below is an example request invoked on patient-view with a patient included:
114
114
115
115
```json
116
116
{
@@ -141,10 +141,10 @@ In some cases, additional information beyond what is included in the prefetch ma
141
141
It is recommended FHIR servers implement, and CDS Services follow, locale specific implementation guides. In the US, the recommended implementation guides to follow are the [Argonaut Data Query Guide (DSTU2)](http://www.fhir.org/guides/argonaut/r2/) or [HL7 US Core (STU3)](http://hl7.org/fhir/us/core/index.html). Each profile page within these implementation guides includes queries FHIR servers are required to support.
142
142
143
143
### Expose non-secured FHIR server for testing
144
-
A non-secured FHIR server is important to support testing with a CDS Service. When the EHR moves a hook to production the system is expected to follow the guidelines in the [security](specification/1.0/#security-and-safety) requirements.
144
+
A non-secured FHIR server is important to support testing with a CDS Service. When the CDS Client moves a hook to production the system is expected to follow the guidelines in the [security](specification/1.0/#security-and-safety) requirements.
145
145
146
146
### Render card
147
-
The CDS Service will provide a response in the form a of a 'card'. Your EHR needs to be able to display the card.
147
+
The CDS Service will provide a response in the form a of a 'card'. Your CDS Client needs to be able to display the card.
148
148
149
149
Example card JSON:
150
150
@@ -172,7 +172,7 @@ Example card rendered: .
175
+
For some CDS Services the end step will just display the card. For the patient-view hook discussed here, we are focused on launching a SMART app. The CDS Hooks guide places no additional constraints for launching a SMART app beyond those from [SMART on FHIR](http://hl7.org/fhir/smart-app-launch/1.0.0/).
0 commit comments