Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
Het afsprakenstelsel maakt gebruik van JSON Web Tokens (JWT) voor de communicatie van informatie tussen partijen in de context van een datadienst. JWT (JSON Web Token) is een open standaard die een compacte en op zichzelf staande manier definieert om informatie veilig te verzenden tussen partijen door een JSON-object. In het afsprakenstelsel worden JWTs digitaal getekend (als JWS volgens RFC 7515), waardoor informatie in de JWTs kan worden vertrouwd (zie Ondertekening van JWTs).
Het DSGO definieert twee soorten JWTs die voor verschillende doeleindes worden gebruikt. Een Authenticatie JWT om informatie over de identiteit van een partij te communiceren, en een Onweerlegbaarheid JWT die boven op de Authenticatie JWT additionele informatie bevat (zoals beschreven in ETSI TS 119 182-1) om de onweerlegbaarheid van content waar in de JWT naar wordt verwezen te garanderen. De Authenticatie JWT is gelijk aan de iSHARE JWT gedefinieerd in iSHARE (v2.0).
JWT Header
DSGO.Basis: Partijen MOETEN in Authenticatie JWTs de parameters zoals opgesteld in de onderstaande tabel gebruiken als JWT headers
DSGO.Basis: Partijen MOETEN in Onweerlegbaarheid JWTs de parameters zoals opgesteld in de onderstaande tabel gebruiken als JWT headers
DSGO.Basis: Partijen MOGEN in alle JWTs andere parameters NIET als JWT headers gebruiken
JWT headers
Beschrijving
van toepassing voor:
Authenticatie JWT
Onweerlegbaarheid JWT
alg
Vereist
Vereist
Als beschreven in RFC 7515, MOET ingevuld worden als RS256
b64
Niet aanwezig
Vereist
Als beschreven in RFC 7797, MOET ingevuld worden als false
crit
Niet aanwezig
Vereist
Als beschreven in RFC 7515, MOET ingevuld worden als ["sigD","b64"]
sigD
Niet aanwezig
Vereist
Als beschreven in ETSI TS 119 182-1, MOET ingevuld worden volgens de tabel hieronder
typ
Vereist
Vereist
Als beschreven in RFC 7515, MOET ingevuld worden als JWT voor een Authenticatie JWT en JOSE voor een Onweerlegbaarheid JWT
De sigD header is toegevoegd in de Onweerlegbaarheid JWT om een handtekening over specifieke HTTP headers en de HTTP body te kunnen zetten om deze te beveiligen.
sigD header parameter
Beschrijving
sigD header parameter
Beschrijving
mId
Als beschreven in ETSI TS 119 182-1, is een URI die het mechanisme voor refereren en verwerken van alle gerefereerde dataobjecten beschrijf, MOET gelijk zijn aan http://uri.etsi.org/19182/HttpHeaders
pars
Als beschreven in ETSI TS 119 182-1, bevat een array van strings als parameters die met dit mechanisme getekend worden, MOET ingevuld worden met de hieronder beschreven velden.
HTTP Header fields
Beschrijving
(request target)
Enkel van toepassing voor HTTP requests
host
Indien aanwezig
content-type
Indien aanwezig
content-encoding
Indien aanwezig
digest
Het tekenen hiervan borgt dat de inhoud van de datadienst wordt gebonden aan de executie van de datadienst.
LicensePurpose
Indien aanwezig, het tekenen hiervan borgt dat de licentie waaronder de data wordt gegeven wordt vastgelegd.
Een JWT header ziet er bijvoorbeeld uit zoals hieronder:
Voor de borging van interoperabiliteit in het DSGO, is het een best practice om geen datadienst gerelateerde JWT claims toe te voegen. Datadienst specifieke claims zouden in de resource moeten worden meegenomen.
DSGO.Basis: Partijen ZOUDEN in alle JWTs NIET andere JWT claims MOETEN definiëren en gebruiken, afhankelijk van het specifieke gebruik van de JWT
Voor de Authenticatie JWT en de Onweerlegbaarheid JWT is de JWT payload gelijk aan elkaar. Het afsprakenstelsel volgt RFC7519 in het gebruik van de JWT payload.
Merk op, volgens ETSI TS 119 182-1 zou de JWT payload van de Onweerlegbaarheid JWT “detached” moeten zijn (zoals beschreven in RFC 7515 Appendix F). Dit houdt in dat de JWT payload leeg zou moeten zijn. Echter, in het DSGO zijn JWT claims essentieel voor de borging van authenticiteit van de verzender. Daarom wordt dit niet gevolgd.
DSGO.Basis: Partijen MOETEN in alle JWTs de JWT claims opstellen zoals beschreven in de onderstaande tabel volgens RFC7519
DSGO.Basis: Partijen MOETEN in alle JWTs alle JWT claims binnen 30 seconden laten verlopen, aantoonbaar door de combinatie van iat en exp claims.
DSGO.Basis: Partijen MOETEN in alle JWTs de JWT claims de iat en exp claims noteren in seconden en MOGEN iat en exp claims NIET noteren in milliseconden
Claims
Beschrijving
Claims
Beschrijving
iss
Vereist
Als beschreven in RFC7519, dit MOET een Organisatie ID (EORI of KvK-nummer) zijn als identificerend kenmerk
sub
Vereist
Als beschreven in RFC7519, dit MOET een Organisatie ID (EORI of KvK-nummer) zijn als identificerend kenmerk
aud
Vereist
Als beschreven in RFC7519, dit MOET een Organisatie ID (EORI of KvK-nummer) zijn als identificerend kenmerk
Als beschreven in RFC7519, dit MOET per organisatie een uniek identificerend kenmerk zijn van de JWT
ret
Optioneel
ret (related to) MOET een eerder ontvangen waarde van jti bevatten
De ret claim is optioneel toegevoegd aan de JWT om een JWT in een respons te koppelen aan een ontvangen verzoek. Hiermee kan na een transactie worden bewezen dat een respons is gestuurd in reactie op een specifiek verzoek.
Een JWT payload voor een JWT ziet er bijvoorbeeld uit zoals hieronder (gebaseerd op voorbeeld van iSHARE (v2.0) - JSON Web Token)
DSGO.Basis: Partijen MOETEN een getekende JWT maar één keer accepteren
DSGO.Basis: Partijen MOETEN een JWT niet accepteren als:
De handtekening ongeldig is,
Deze niet aan hen geadresseerd is, op basis van de aud claim,
Deze niet verlopen is, op basis van de exp claim,
Deze niet eerder ontvangen is, op basis van de jti claim met inachtneming van de verlooptijd
JSON Web Encryptie (JWE)
JSON Web Encryptie (JWE) is een encryptie methode die toegepast kan worden om alle JWTs te beveiligen wanneer gesigneerde JWTs niet veilig genoeg zijn, beschreven in RFC 7516. Bijvoorbeeld wanneer informatie in JWT’s niet onversleuteld gelogd mag worden. Wanneer dit gewenst is gegeven de specifieke context van een datadienst, kan dit worden toegepast. iSHARE (v2.0) geeft een beschrijving van het gebruik van JWE.
DSGO.Basis: Partijen MOGEN gebruik maken van JWE als beschreven in RFC 7516
Merk op, Momenteel worden er geen afspraken gemaakt over JWE. Wanneer er meerdere security levels worden gedefinieerd of aanvullende beveiliging nodig is ten behoeve van use cases worden gedetailleerde afspraken over JWE mogelijk opgenomen in het afsprakenstelsel.