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.
Hoe JWT toe te passen
Het JWT token wordt als http header meegestuurd. Het JWT token bestaat uit 3 onderdelen:
header, payload data en ondertekening.
De 3 onderdelen worden gescheiden door een punt en het geheel wordt base64 geencodeerd:
JWT nader bekeken
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. Voeg de hash toe aan payload data. De payload data bevat een aantal parameters (claims), deze worden hieronder nader uitgewerkt.
4. Maak het JWS token. Dit bestaat uit het maken van de header en payload. Header bevat een aantal parameters (claims), deze worden hieronder uitgewerkt.
5. Onderteken het bericht met behulp van de private key.
6. Encodeer het bericht.
1. Stel het registreer/update endpoint bericht samen dat naar OSR wordt gestuurd.
hieronder is de body weergegeven van endpoint te 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"
}
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.
Er is een online tool beschikbaar om jwt tokens samen te stellen:
![]() |
jwt.io |
Hieronder is een voorbeeld weergegeven van het gedecodeerde JWT token:
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="
}
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. | Verplicht | |
nbf | Not before. Dit geeft de startdatum aan wanneer het JWT token gebruikt mag worden | Verplicht | |
exp | Expiration date. Dit geeft aan tot wanneer het JWT token gebruikt mag worden | Verplicht | |
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 | Verplicht | |
hash* | Verplicht | Verplicht |
* De volgende transformaties moeten worden gedaan om de hash te verkrijgen:
* body -> SHA256 -> base64 encoding