Describe the use of the traceparent header

Fixes #143
ehealthsuisse · Feb 22, 2024 · 4f6f6c4 · 4f6f6c4
1 parent add5b05
commit 4f6f6c4
Show file tree

Hide file tree

Showing 15 changed files with 95 additions and 5 deletions.
diff --git a/input/ch.fhir.ig.ch-epr-mhealth.xml b/input/ch.fhir.ig.ch-epr-mhealth.xml
@@ -597,6 +597,11 @@ Relationship in the Swiss examples (CN=CommunityA:00000001001,OU=Relationship,DC
                     <title value="Sequence Diagrams"/>
                     <generation value="markdown"/>
                 </page>
+                <page>
+                    <nameUrl value="tracecontext.html"/>
+                    <title value="Trace Context"/>
+                    <generation value="markdown"/>
+                </page>
                 <page>
                     <nameUrl value="openissues.html"/>
                     <title value="Open Issues / Change Log"/>

diff --git a/input/fsh/ex-audit-65.fsh b/input/fsh/ex-audit-65.fsh
@@ -42,4 +42,5 @@ Usage: #example
 * entity[submissionSet].role = http://terminology.hl7.org/CodeSystem/object-role#20 "Job"
 * entity[submissionSet].what.identifier.system = "urn:ietf:rfc:3986"
 * entity[submissionSet].what.identifier.value = "urn:oid:1.3.6.1.4.1.12559.11.13.2.6.2949"
-
+* entity[+].what.identifier.value = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
+* entity[=].type = https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType#XrequestId
diff --git a/input/includes/menu.xml b/input/includes/menu.xml
@@ -93,6 +93,9 @@
             <li>
                 <a href="sequencediagrams.html">Sequence diagrams</a>
             </li>
+            <li>
+                <a href="tracecontext.html">Trace Context</a>
+            </li>
             <li>
                 <a href="openissues.html">Open Issues / Change Log</a>
             </li>

diff --git a/input/pagecontent/iti-103.md b/input/pagecontent/iti-103.md
@@ -98,7 +98,7 @@ There are no CapabilityStatement resources defined for this transaction.
 
 ### Security Consideration
 
-There are no special security requirements for this transaction.
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
 
 #### Security Audit Considerations
 

diff --git a/input/pagecontent/iti-104.md b/input/pagecontent/iti-104.md
@@ -50,6 +50,7 @@ Add Patient [Franz Muster](Patient-PatientPIXmFeed.json.html):
 PUT http://example.org/fhir/Patient?identifier=urn:oid:2.16.756.888888.3.1|8734 HTTP/1.1
 Accept: application/fhir+json
 Content-Type: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 
 {
   "resourceType" : "Patient",
@@ -120,6 +121,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Patient Identity Feed FHIR_ [ITI-104] request must authorize using the 
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Identity Source Audit

diff --git a/input/pagecontent/iti-20.md b/input/pagecontent/iti-20.md
@@ -51,3 +51,5 @@ The CapabilityStatement resource for the **Audit Record Repository** is
 ### Security Consideration
 
 TLS SHALL be used.
+
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
diff --git a/input/pagecontent/iti-65.md b/input/pagecontent/iti-65.md
@@ -79,6 +79,8 @@ Document Recipient using the IUA profile with extended access token. Consequentl
 the _Provide Document Bundle_ [ITI-65] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html)
 transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Source Audit

diff --git a/input/pagecontent/iti-66.md b/input/pagecontent/iti-66.md
@@ -32,6 +32,7 @@ _Find Document List_ example **request**:
 ```
 GET [base]/List?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
 Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 #### Find Document Lists Response Message
@@ -53,6 +54,8 @@ TLS SHALL be used. This national extension enforces authentication and authoriza
 Responder using the IUA profile with extended access token. Consequently the _Find Document Lists_ [ITI-66] request 
 must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Consumer Audit

diff --git a/input/pagecontent/iti-67.md b/input/pagecontent/iti-67.md
@@ -32,6 +32,7 @@ _Find Document Reference_ example **request**:
 ```
 GET [base]/DocumentReference?patient.identifier=urn:oid:2.999|11111111 HTTP/1.1
 Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 #### Find Document References Response Message

diff --git a/input/pagecontent/iti-68.md b/input/pagecontent/iti-68.md
@@ -40,6 +40,8 @@ Document Responder using the IUA profile with extended access token. Consequentl
 the _Retrieve Document_ [ITI-68] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html)
 transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Document Consumer Audit

diff --git a/input/pagecontent/iti-71.md b/input/pagecontent/iti-71.md
@@ -575,6 +575,8 @@ There are no CapabilityStatement resources defined for this transaction.
 IUA Authorization Clients, Authorization Servers and Resource Server actors SHALL use the JWS (signed) alternative 
 of the JWT token as specified in the IUA Trial Implementation. The JWE alternative SHALL not be used.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 There is no audit event required for this transaction.
diff --git a/input/pagecontent/iti-78.md b/input/pagecontent/iti-78.md
@@ -49,6 +49,7 @@ Query for a patient with name Muster and birthdate 1995-01-27.
 ```
 GET [base]/Patient?name=Muster&birthdate=1995-01-27
 Accept: application/fhir+json; fhirVersion=4.0
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 [Example response to above query](Bundle-PDQm-QueryResponse.json.html)
 
@@ -57,6 +58,7 @@ Query for a patient with name M returning too many results:
 ```
 GET [base]/Patient?name=M
 Accept: application/fhir+json; fhirVersion=4.0
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 [Example response to above query](Bundle-PDQm-QueryResponseTooManyResults.json.html)
 
@@ -88,6 +90,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Mobile Patient Identifier Cross-reference Query_ [ITI-83] request must authorize using the
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Demographics Consumer Audit

diff --git a/input/pagecontent/iti-83.md b/input/pagecontent/iti-83.md
@@ -55,7 +55,10 @@ Query for a patient with a local id of 123 by AssigningAuthority oid 1.2.3 which
 community where the Assigning Authority is oid 5.6.7 and the MPI-PID and EPR-SPID are requested:
 
 ```
-GET [base]/Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.1.2.3|123&targetSystem=urn:oid:2.999.5.6.7&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3
+GET [base]/Patient/$ihe-pix?sourceIdentifier=urn:oid:2.999.1.2.3|123&targetSystem=urn:oid:2.999.5.6.7&targetSystem=urn:oid:2.16.756.5.30.1.127.3.10.3 HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
+
 ```
 
 #### Response message
@@ -109,6 +112,8 @@ Patient Identifier Cross-reference Manager using the IUA profile with basic acce
 the _Mobile Patient Identifier Cross-reference Query_ [ITI-83] request must authorize using the 
 [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 ##### Patient Identifier Cross-reference Consumer Audit

diff --git a/input/pagecontent/iti-90.md b/input/pagecontent/iti-90.md
@@ -33,13 +33,17 @@ The _Find Matching Care Services_ message is a FHIR search operation on the mCSD
 A _Care Services Selective Consumer_ initiates a search request using HTTP GET or POST:
 
 ```
-GET [base]/[resource]?[parameters]
+GET [base]/[resource]?[parameters] HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 ```
 
 or
 
 ```
-POST [base]/[resource]/_search
+POST [base]/[resource]/_search HTTP/1.1
+Accept: application/fhir+json
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
 Content-Type: application/x-www-form-urlencoded
 
 param1=value&param2=value
@@ -158,6 +162,8 @@ TLS SHALL be used. This national extension enforces authentication and authoriza
 Selective Supplier_ using the IUA profile with basic access token. Consequently, the _Find Matching Care Services_
 [ITI-90] request must authorize using the [_Incorporate Access Token_ [ITI-72]](iti-72.html) transaction of the IUA profile.
 
+The `traceparent` header is required, as described in [Trace Context header](tracecontext.html).
+
 #### Security Audit Considerations
 
 Note that the same audit message is recorded by both **Care Services Selective Supplier** and **Care Services 

diff --git a/input/pagecontent/tracecontext.md b/input/pagecontent/tracecontext.md
@@ -0,0 +1,51 @@
+### Trace Context header
+
+For all transaction described in this implementation guide, the HTTP `traceparent`
+header is required. This header is defined in the
+[W3C Trace Context Recommendation](https://www.w3.org/TR/trace-context/).
+
+The header value is made of four parts separated by dashes: the **version**, **trace-id**, **parent-id** and
+**trace-flags**. For example:
+
+```http
+GET /request HTTP/1.1
+traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00
+```
+
+- The **version** is currently set to `00`.
+- The **trace-id** is a unique identifier for this transaction instance (i.e. an HTTP request and its response).
+  Consecutive HTTP requests SHALL NOT have the same trace-id, even if it is a retry. The HTTP request and its response
+  SHALL have the same trace-id. It is a 16-byte array encoded as 32 hexadecimal characters, all lowercase.
+- The **parent-id** is a unique identifier for this message (a request and response are two different messages). The
+  HTTP response SHALL have a different identifier than the request. It is an 8-byte array, encoded as 16 hexadecimal
+  characters, all lowercase.
+- The **trace-flags** is used to communicate tracing flags with the consumer. This implementation guide specifies no
+  requirements for this field, it is recommended using the value `00`.
+
+Each actor shall support the `traceparent` header. Grouped actors shall use the same **trace-id** value to correlate IHE transactions.
+
+##### Audit event requirements
+
+The `traceparent` header value of the generated message SHALL be added to the generated Audit Event: for the client, the
+header value of the request; for the responder, the header value of the response.
+It is described as an `AuditEvent.entity`, with the system `https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType#Traceparent`, as demonstrated below.
+
+```json
+{
+  "resourceType" : "AuditEvent",
+  /* Rest of the AuditEvent */
+  "entity" : [
+    {
+      "what" : {
+        "identifier" : {
+          "value" : "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00"
+        }
+      },
+      "type" : {
+        "system" : "https://profiles.ihe.net/ITI/BALP/CodeSystem/BasicAuditEntityType",
+        "code" : "Traceparent"
+      }
+    }
+  ]
+}
+```