Add optional tenant JWT payload field (fixes #205) (#420)

Additionally, the example JWT has been improved to include the public and private keys used to both sign and verify the signature.

Author: kpshek

docs/specification/1.0.md

@@ -502,6 +502,7 @@ aud | REQUIRED | *string* or *array of string* | The CDS Service endpoint that i
 exp | REQUIRED | *number* | Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC).
 iat | REQUIRED | *number* | The time at which this JWT was issued, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC).
 jti | REQUIRED | *string* | A nonce string value that uniquely identifies this authentication JWT (used to protect against replay attacks).
+tenant | OPTIONAL | *string* | An opaque string identifying the healthcare organization that is invoking the CDS Hooks request.
 
 CDS Services SHOULD whitelist the `iss`, `jku` and `sub` fields to only the EHRs they trust.
 
@@ -511,30 +512,62 @@ The EHR MUST make its public key, expressed as a JSON Web Key (JWK) in a JWK Set
 
 The EHR MAY make its JWK Set available via a URL identified by the `jku` header field, as defined by [rfc7515 4.1.2](https://tools.ietf.org/html/rfc7515#section-4.1.2). If the `jku` header field is ommitted, the EHR and CDS Service SHALL communicate the JWK Set out-of-band.
 
-An example JSON web token header and payload:
+An example JSON web token header, payload, and JWK set:
 
 ```json
+// JSON Web Token Header
 {
   "alg": "ES384",
   "typ": "JWT",
   "kid": "example-kid",
   "jku": "https://fhir-ehr.example.com/jwk_uri"
 }
 
+// JSON Web Token Payload
 {
   "iss": "https://fhir-ehr.example.com/",
   "sub": "client_id",
   "aud": "https://cds.example.org/cds-services/some-service",
   "exp": 1422568860,
   "iat": 1311280970,
-  "jti": "ee22b021-e1b7-4611-ba5b-8eec6a33ac1e"
+  "jti": "ee22b021-e1b7-4611-ba5b-8eec6a33ac1e",
+  "tenant": "2ddd6c3a-8e9a-44c6-a305-52111ad302a2"
+}
+
+// JSON Web Key Set (public key)
+// This public key is used by the CDS Service to verify the signature of the JWT
+{  
+  "keys":[  
+    {  
+      "kty": "EC",
+      "use": "sig",
+      "crv": "P-384",
+      "kid": "example-kid",
+      "x": "46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk",
+      "y": "XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI",
+      "alg": "ES384"
+    }
+  ]
+}
+
+// JSON Web Key (private key)
+// This private is used by the EHR to sign the JWT
+{  
+  "kty": "EC",
+  "d": "SeFXUXda8UomZ8GFUl7HH_Oi15rIbfMcsWj9ecIsDR8kLbqsEz2CGNgwy_IcILxy",
+  "use": "sig",
+  "crv": "P-384",
+  "kid": "example-kid",
+  "x": "46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk",
+  "y": "XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI",
+  "alg": "ES384"
 }
 ```
 
-Using the above JWT payload, the complete JWT as passed in the Authorization HTTP header would be:
+Using the above JWT values and JWKs, the complete JWT as passed in the Authorization HTTP header would be:
 
 ```
-Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsInN1YiI6ImNsaWVudF9pZCIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIn0.230VxOubItskK-HCzdfjR5Y76nEydquQoqK-JDHbl8y8wzo-7HJetYpY1R4rytp_yJJCc8DULX9G5llPKx6opQ
+Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsInN1YiI6ImNsaWVudF9pZCIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIiwidGVuYW50IjoiMmRkZDZjM2EtOGU5YS00NGM2LWEzMDUtNTIxMTFhZDMwMmEyIn0.CUFPkplnWd6YGIvzoHolWCQBDsCL8QtTWKGg_QFpS169WrqDGzktRi-_we6-6rVzbjerU27ZKww_SW0-b9RTz-dPJNcqsueMio8r6EqXUXhbLm_ch3XFSbDlGHDl_tqo
 ```
 
 ### Cross-Origin Resource Sharing