OSR:2019/JWT

Uit Kennisnet Developers Documentatie
< OSR:2019
Versie door Delange02 (overleg | bijdragen) op 8 mrt 2019 om 14:32 (JWT nader bekeken)
Ga naar: navigatie, zoeken

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:

Homepage icon.png 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 maart 2019 vind er een update plaats aan de invulling van onderstaande header- en payload parameters binnen het OSR. Dit om in een zo vroeg mogelijk stadium te voldoen aan de aankomende Edukoppeling-definitie rondom REST-services. De meest recente versie van het Edukoppeling-document omtrent deze definitie kunt u hier bekijken.

Klik op de link "uitvouwen" aan de rechterkant om het nieuwe parameteroverzicht te tonen.

Header parameters

# Claim Waarde Omschrijving Verplicht/Optioneel
h1 alg RS256 Het algoritme van de key wordt hier aangegeven Verplicht
h2 jwk Bevat het parameters van het PKIo certificaat dat gebruikt is voor de ondertekening van het bericht. Verplicht
h2.1 kty Type van het PKIo certificaat, “RSA”. Verplicht
h2.2 n Modulus van de publieke RSA sleutel van het x509 (PKIo) certificaat, geëncodeerd als base64url integer. Verplicht
h2.3 e AQAB Exponent van de publieke RSA sleutel, geencodeerd als besa64url integer. Verplicht
h2.4 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
h2.5 kid Key ID, wordt gebruikt om de juiste sleutel te kunnen kiezen als er meerdere publieke sleutels in de lijst zijn opgegeven. Optioneel
h2.6 use sid Zegt waar de sleutel voor gebruikt wordt, kan “sign” of “enc” bevatten voor respectievelijk ondertekenen of versleutelen. Hiermee kun je aangeven waar deze sleutel voor gebruikt wordt. Optioneel

* Naast x5c zal ook x5u onderdeel gaan uitmaken van de Edukoppeling Standaard, maar OSR ondersteund deze claim in de huidige release nog niet.

Payload parameters

# Claim Waarde Omschrijving Verplicht/Optioneel
p1 iss Afzender van het bericht (issuer), notatie ‘edustd:oin’ || [de OIN van de afzenderorganisatie] of ‘edustd:oin’ || [de OIN van de afzenderorganisatie inclusief administratie-kenmerk] Verplicht
p2 aud Geadresseerden van het bericht (audience). Hier kan een enkele geadresseerde worden ingevuld in een string-notatie, of een lijst van geadresseerden. De notatie voor geadresseerden is ‘edustd:oin’ || [OIN van de geadresseerde], of ‘edustd:oin’ || [OIN van de geadresseerde inclusief zijn administratie-kenmerk]. Verplicht
p3 sub Onderwerp van de berichtuitwisseling (subject). Hier is mogelijk om hier het service-version kenmerk (d.w.z. de namespace van de service) in te vullen, zodat deze informatie beschikbaar is om additionele gegevens van de service en zijn endpoint in het OSR op te zoeken. Optioneel
p4 iat Timestamp (milliseconden sinds epoch) waarop het token is aangemaakt (issued at). Verplicht
p5 nbf Tijdstip (milliseconden sinds epoch) vanaf welke het JWT token geldig is (not before). Als niet opgegeven, gelijk aan ‘iat’. Optioneel
p6 exp Tijdstip (milliseconden sinds epoch) tot welke het JWT token geldig is (expires). Als niet opgegeven, een uur (3.600.000 milliseconden) na iat. Optioneel
p7 edustd:body "edustd:body":{"hash":"...","alg":"B64SHA256"} Container voor velden 7.1 en 7.2. Verplicht
p7.1 hash De base64url-geëncodeerde hashwaarde van het bericht zelf. Verplicht
p7.2 alg B64SHA256 Het algoritme waarmee de hashwaarde van het bericht is bepaald. Verplicht

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:

Jwt structuur.jpg