JSON Web Tokens (Transactional)

Overview

Medicus makes use of JSON Web Tokens (JWT) to ensure that data flowing between Medicus and the consumer system is cryptographically verified.

A JWT token should be sent with each request made to a Transactional or Patient Facing Services API endpoint.

Signing JWT Signatures

Medicus uses the HMAC SHA256 alongside the RS256 signing algorithm.

RS256 ensures that only the private key holder and no one else can sign tokens. JWTs are signed with the consumer’s private key and validated by the Medicus tenant using the public key stored on the Medicus Developer Portal.

Consumers should use the Medicus Developer Portal to upload and rotate public keys. Keys without re-deploying the application with a new secret.

Signature Formation

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

To create the signature, the Base64-encoded header and payload are taken, along with a secret, and signed with the algorithm specified in the header.

In this case, the secret is the consumer’s private key.

Example signature formation:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

JWT Structure

JOSE Header

A JSON object containing the parameters describing the cryptographic operations and parameters employed.

Example header payload:

{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "3cd60f2e-70a5-11ed-95ba-0a58a9feac02"
}

JWS Payload

The payload contains statements about the entity and additional entity attributes, which are called claims.

Example body payload:

{
    "iss": "8010045b-d53f-4675-acd4-e9694709c9d3",
    "aud": "https://a10001.api.medicus.health/pfs-api/v1/patient/1339a7c3-28d6-11eb-adc1-0242ac120002/prescriptions",
    "exp": 1490922820,
    "userName": "medicus",
    "userEmail": "medicususer@mail.com",
    "userIdentifierType": "gb-gmc-number",
    "userIdentifierValue": "a83569be-3fc8-4396-b11e-0faeefaa5fe3",
    "softwareSystem": "Healthcare App V1 iOS",
    "applicationName": "My Requesting App",
    "organisationName": "Pharmacy Co"
}

Payload Validation

The JWT token is validated upon each API request:

• The token must be signed by the key specified in kid

• kid must belong to the issuer iss

• exp must not be in the past (Medicus allows 30 seconds for skew)

• exp must not be more than 5 minutes in the future (to avoid long-dated JWT Tokens being generated)

• aud must match the Medicus tenant URL handling the request

• alg must be RS256

• iss must be approved by the healthcare organisation to have access to the Medicus tenant

• kid must relate to an “active” key (keys can be deactivated or rotated)

Making Requests

The JWT should be included as part of the Bearer in the Authorization HTTP header.

Example request:

GET https://a10001.api.test.medicus.health/pfs-api/v1/patient/1222aa9c-28d6-11eb-adc1-0242ac120002/nominated-eps-dispensers
Authorization: Bearer [JWT Token]

Example CURL request, including the Authorization header:

curl --location --request GET 'https://a10001.api.test.medicus.health/pfs-api/v1/patient/ed9a308e-360c-11ed-8b36-060b232f1aa2/dob' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjNjZDYwZjJlLTcwYTUtMTFlZC05NWJhLTBhNThhOWZlYWMwMiJ9.eyJpc3MiOiIwNWY2OGNiOC03MGE1LTExZWQtOTQ2Ni0wYTU4YTlmZWFjMDIiLCJraWQiOiIzY2Q2MGYyZS03MGE1LTExZWQtOTViYS0wYTU4YTlmZWFjMDIiLCJhdWQiOiJodHRwczovL2ExMDAwMS5hcGkuc3RhZ2luZy5tZWRpY3VzLmhlYWx0aC90cmFuc2FjdGlvbmFsLWFwaS92MS9maWxlL2NhcmUtcmVjb3JkLWRvY3VtZW50LzMzMWRmOWFjLTY3NGUtMTFlZC05YTc2LTA2Mzk5ZjkwNzIyZS8zMzFkZjlhYy02NzRlLTExZWQtOWE3Ni0wNjM5OWY5MDcyMmUiLCJleHAiOjE2NzE0MzkxNjZ9.1DIRypATDkc9nBszy8eRignV0KbVh2_mA5jdpW98m7bodOmm5PvJHWK-VanPxKGIjr7O2AlyJyGI5Cz_LLXTzo0rNLl4GThkiRKnBzi4PewR_1vFo9Za1VmoTnCQVznej6WNjFc73OXIYSjLAaGs3Pa-4lDTCNQFwQF79MqZTOQ

Error States