From 15e3ef259a3a487ad1428619da6097cb6ef0a193 Mon Sep 17 00:00:00 2001 From: Quentin Ligier Date: Mon, 5 Feb 2024 12:43:20 +0100 Subject: [PATCH] Describe the use of the traceparent header Fixes #143 --- input/ch.fhir.ig.ch-epr-mhealth.xml | 5 +++ input/fsh/ex-audit-65.fsh | 3 +- input/includes/menu.xml | 3 ++ input/pagecontent/iti-103.md | 2 +- input/pagecontent/iti-104.md | 3 ++ input/pagecontent/iti-20.md | 2 ++ input/pagecontent/iti-65.md | 2 ++ input/pagecontent/iti-66.md | 3 ++ input/pagecontent/iti-67.md | 1 + input/pagecontent/iti-68.md | 2 ++ input/pagecontent/iti-71.md | 2 ++ input/pagecontent/iti-78.md | 4 +++ input/pagecontent/iti-83.md | 7 +++- input/pagecontent/iti-90.md | 10 ++++-- input/pagecontent/tracecontext.md | 50 +++++++++++++++++++++++++++++ 15 files changed, 94 insertions(+), 5 deletions(-) create mode 100644 input/pagecontent/tracecontext.md diff --git a/input/ch.fhir.ig.ch-epr-mhealth.xml b/input/ch.fhir.ig.ch-epr-mhealth.xml index 568e36d..a1af62a 100644 --- 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 <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 index a7acb71..ae738b7 100644 --- 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 index 1ff5162..df0ede9 100644 --- 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 index b07f163..ea7c630 100644 --- 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 index 506a168..03ac92f 100644 --- 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 index e13a38c..96b5ded 100644 --- 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 index 2543483..1b7efee 100644 --- 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 index 68888e8..05a3c6f 100644 --- 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 index 08e6d20..101c8b3 100644 --- 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 index f63e9d9..47c10bf 100644 --- 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 index 4eebb21..d661c86 100644 --- 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 index 1da18f6..1e52313 100644 --- 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 index e2952e1..43743a9 100644 --- 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 index c75cc0a..fe8895d 100644 --- 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¶m2=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 new file mode 100644 index 0000000..51d58ee --- /dev/null +++ b/input/pagecontent/tracecontext.md @@ -0,0 +1,50 @@ +### 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). + It is a 16-byte array encoded as 32 hexadecimal characters, all lowercase. +- The **parent-id** is a unique identifier for this message. 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" + } + } + ] +} +```