OSR:2019/JWT

Waarom JWT

Voor de services 'registreren' en 'updaten' van endpoints wordt JWT toegepast om vast te stellen dat het bericht onderweg niet aangepast is en ondertekend is door degene die het bericht heeft opgesteld.
Binnen de onderwijsketen maken we afspraken over de manier waarop we ondertekening uitvoeren en controleren.
Deze afspraken worden vastgelegd in een Edukoppeling profiel, analoog aan de Edukoppeling afspraken die er voor de beveiliging van SOAP berichten worden gemaakt.

JWT nader bekeken

Er is een online tool beschikbaar om jwt tokens mee samen te stellen:

jwt.io

Op de volgende pagina vindt u referenties naar JWT documentatie: Belangrijke JWT documentatie

Het aanmaken van JWT tokens worden voor het grootste gedeelte automatisch door de libraries van uw ontwikkelplatform gegenereerd.
(zie jwt.io voor een lijst met beschikbare libraries).

Het JWT token wordt als http header meegestuurd. Om een JWT token te creëren moeten de volgende stappen worden uitgevoerd:

• 1. Stel het registreer/update endpoint bericht samen dat naar OSR wordt gestuurd.
  
• 2. Maak een base64 geëncodeerde SHA256 hash voor het bericht aan.
  
• 3. Maak de header en payload.
• 4. Maak het JWS token en onderteken het bericht met behulp van de private key en encodeer het totale bericht.
  

• 1. Stel het registreer/update endpoint bericht samen dat naar OSR wordt gestuurd.
  

hieronder is een voorbeeld bericht weergegeven van endpoint registreren:

{
"mandate_token":"6a47bfdd-81a7-46cd-b41f-d907e91ebdfc",
"administration_id": "0000000700004HR77707",
"service_version_namespace": "http://xml.eld.nl/schemas/Overstapservice/20170601",
"url": "https://t2.nl"
}

• 2. Maak een base64 geëncodeerde SHA256 hash voor het bericht aan.
  

Het OSR biedt een service aan om een json bericht te hashen met base64 SHA256 encoding. Het OSR controleert uiteindelijk de hash op basis van het registreer/update bericht.

POST /api/v1/jwt/hash

• 3. Maak de header en payload.

Header en payload bevatten een aantal parameters (claims), deze worden hieronder uitgewerkt.

Voeg de hash toe aan payload data.

header
{
  "alg": "RS256",
  "type": "JWT",
  "jwk": {
    "kty": "RSA",
    "n": "25wryfsgd_OVH4_RAy6afe-ruuzKrK58zJK- …jjj ",
    "e": "AQAB",
    "x5c": [
      "MIIFijCCA3KgAwIBAgIJANIncLtaUQHdMA… /rV"
    ],
    "x5t": "vzAuinLys_OgCFLDv_G2CJQdUhY",
    "x5t#256": "jkrWxwlbDlMSA3OzQOMhBJo0tjlLbp4IbDpAgwYOFGA",
    "kid": "Kennisnet signing certificate",
    "alg": "RS256",
    "use": "sig"
  }
}

Payload data

{
  "iat": 1548330681,
  "nbf": 1548330681,
  "exp": 1548334281,
  "aud": "00000003272448340204",
  "iss": "00000003272448340116",
  "hash": "DmSGW0lCV3OSNp/rVgGpodZ/Hcuje5ciQkiDqPhFpAk="
}

Let op: Vanaf 18 vind er een update plaats aan de invulling van header- en payload parameters binnen het OSR. Dit om in een zo vroeg mogelijk stadium te voldoen aan de aankomende Edukoppeling-definities rondom REST services. Nadere invulling volgt.

Header parameters

Parameters	Waarde	Omschrijving	Verplicht/Optioneel
alg	RS256	Het algoritme van de key wordt hier aangegeven	Verplicht
type	JWT	Typering van het token	Verplicht
Jwk kty	RSA	Key type	Verplicht
n		Modulus van het pem certificaat	Verplicht
e	AQAB	Exponent van het pem certificaat	Verplicht
x5c		x509 certifcate chain. Hiermee kan worden geverifieerd of het certificaat is uitgegeven door de juiste CA en of het op blacklist staat van de revoke list	Verplicht
x5t		Thumbprint van x509 certificaat	Verplicht
x5t#256			Verplicht
kid		Een naam om het certificaat te onderscheiden	Verplicht
alg		Algoritme van de key	Verplicht
use	sig	Hoe de key gebruikt moet worden. Bij OSR gaat het om het ondertekenen van een bericht.	Verplicht

Payload parameters

Parameters	Omschrijving	Verplicht/Optioneel
iat	Issued at. Dit geeft de datum aan wanneer het JWT token is aangemaakt.	Optioneel
nbf	Not before. Dit geeft de startdatum aan wanneer het JWT token gebruikt mag worden	Optioneel
exp	Expiration date. Dit geeft aan tot wanneer het JWT token gebruikt mag worden	Optioneel
aud	Audience. Dit geeft aan voor wie het JWT token is aangemaakt. In het geval een POST/PUT naar OSR is dit altijd Kennisnet	Verplicht
iss	Issuer. Degene die het JWT token heeft aangemaakt	Optioneel
hash*	Hash waarde van de body data. De daadwerkelijke body data van de POST/PUT operatie	Verplicht

* De volgende transformaties moeten worden gedaan om de hash te verkrijgen:
* body -> SHA256 -> base64 encoding

• 4. Onderteken het bericht met behulp van de private key en encodeer het totale bericht.
  

De header en payload van het JWT token worden ondertekend met het algoritme en bijbehorende parameters dat in de header van het JWT token is beschreven.
Voor de ondertekening wordt de private sleutel van het PKI-overheids/ODOC certificaat gebruikt. De publieke sleutel wordt meegeleverd in het bericht, zodat de ontvangende partij het bericht kan valideren.

Het uiteindelijk JWT token bestaat uit 3 onderdelen:
header, payload data en ondertekening. Alle onderdelen zijn base64 url geencodeerd.

De 3 onderdelen worden gescheiden door een punt: