Add documentation regarding the JWT payload fields.

Additionally, explicitly document that the public key is expressed as JWK
in a JWK Set.

Author: kpshek

docs/specification/1.0.md

@@ -479,9 +479,19 @@ Each time an EHR transmits a request to a CDS Service, the request MUST include
 ```
 Authorization:  Bearer {{JWT}}
 ```
-Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service.   Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the EHR by the CDS Service.
+Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the EHR by the CDS Service.
 
-The EHR MUST use its private key to digitally sign the JWT, using the [JSON Web Signatures (RFC7515)]( https://tools.ietf.org/html/rfc7515) standard.  The JWT contains the following fields:
+The EHR MUST use its private key to digitally sign the JWT, using the [JSON Web Signatures (rfc7515)](https://tools.ietf.org/html/rfc7515) standard.
+
+The JWT header contains the following fields (see [rfc7515 section 4.1](https://tools.ietf.org/html/rfc7515#section-4.1) for further information on these standard headers):
+
+Field | Priority | Value
+----- | ----- | --------
+alg | REQUIRED | *string* The cryptographic algorithm used to sign this JWT.
+kid | REQUIRED | *string* The identifier of the key-pair used to sign this JWT.
+typ | REQUIRED | *string* Fixed value: `JWT`.
+
+The JWT payload contains the following fields:
 
 Field | Priority | Value
 ----- | ----- | --------
@@ -491,28 +501,34 @@ aud | REQUIRED | *string or array of strings* The CDS Service endpoint that is b
 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)
-kid | REQUIRED | *string* The identifier of the key-pair used to sign this JWT.  
 
 Per [rfc7519](https://tools.ietf.org/html/rfc7519#section-4.1.3), the `aud` value is either a string or an array of strings. For CDS Hooks, this value MUST BE the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of `https://cds.example.org`. When the EHR invokes the CDS Service discovery endpoint, the aud value is either `"https://cds.example.org/cds-services"` or `["https://cds.example.org/cds-services"]`. Similarly, when the EHR invokes a particular CDS Service (say, `some-service`), the aud value is either `"https://cds.example.org/cds-services/some-service"` or `["https://cds.example.org/cds-services/some-service"]`.
 
-An example JSON web token payload:
+The EHR MUST make its public key, expressed as a JSON Web Key (JWK) in a JWK Set, as defined by [rfc7517](https://tools.ietf.org/html/rfc7517). The `kid` value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature.
+
+An example JSON web token header and payload:
 
 ```json
+{
+  "alg": "HS256",
+  "typ": "JWT",
+  "kid": "example-kid"
+}
+
 {
   "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",
-  "kid": "id489183"
+  "jti": "ee22b021-e1b7-4611-ba5b-8eec6a33ac1e"
 }
 ```
 
 Using the above JWT payload, the complete JWT as passed in the Authorization HTTP header would be:
 
 ```
-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIn0.Gwl3s301OMWpdEVAVj_T3JZV8bs7N5-V7QNNG7TQ33o
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIn0.ATQ_bdiMFrKQMz2U-rALxzakOrBSEMtzTtMcDeXiF74
 ```
 
 ### Cross-Origin Resource Sharing