Signing the JWT

Koppeltaal uses JWTs in several places. For the dev guide, two places are good to know about:

1. For retrieving an access token that provides access to the Koppeltaal server.

2. For performing a Koppeltaal launch using HTI or SMART HTI.

What is a JWT?

JWT stands for JSON Web Token. A practical explanation of how a JWT works can be found here. An important piece is:

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

• Header

• Payload

• Signature

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

Signing

The signing of the JWT takes place in the third part of the JWT: the signature (zzzzz in the example above). Koppeltaal uses asymmetric key pairs to sign the JWTs. The signature part is encrypted using the private key of the asymmetric key pair. The public-key part is published at the JWKS endpoint. This proves that a JWT is signed by a party in possession of the private-key. Signing the JWT is most easily performed using a JWT library for the relevant programming language.

The JWT debugger is a great place to see, at runtime, what the contents of the JWT are and what the token looks like. Note that we work with key pairs and not shared secrets. So make sure to select algorithms that work with key pairs like RS and ES.

RSA is more complicated to implement than, say, HMAC algorithms. However, it is a lot more secure. For example, there is no shared secret. Also, using JWKS, it is possible to quickly rotate keys.

Topics

TOP-KT-005c - Applicatie toegang: SMART on FHIR backend services