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).
Op deze pagina worden de generieke afspraken die gelden voor het gebruik van JWT vastgelegd, deze zijn in lijn met de API strategie voor de Nederlandse Overheid, het iSHARE (v2.0) en het Centre of Excellence for Data Sharing and Cloud (CoE-DSC) Use Case Implementation Guide, waarin deze standaard ook gebruikt wordt.
...
Excerpt |
---|
name | JSON Web Token (JWT) 1 |
---|
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOETEN in Authenticatie JWTs de parameters zoals opgesteld in de onderstaande tabel gebruiken als JWT headers
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOETEN in Onweerlegbaarheid JWTs de parameters zoals opgesteld in de onderstaande tabel gebruiken als JWT headers
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOGEN in alle JWTs andere parameters NIET als JWT headers gebruiken
|
|
...
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. |
...
JWT Payload
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.
Excerpt |
---|
name | JSON Web Token (JWT) 2 |
---|
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen ZOUDEN in alle JWTs NIET andere JWT claims MOETEN definiëren en gebruiken, afhankelijk van het specifieke gebruik van de JWT
|
|
...
Excerpt |
---|
name | JSON Web Token (JWT) 3 |
---|
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOETEN in alle JWTs de JWT claims opstellen zoals beschreven in de onderstaande tabel volgens RFC7519
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOETEN in alle JWTs alle JWT claims binnen 30 seconden laten verlopen, aantoonbaar door de combinatie van iat en exp claims.
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| 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 |
---|
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 |
exp
| Vereist | MOET zijn als beschreven in RFC7519 |
iat
| Vereist | MOET zijn als beschreven in RFC7519 |
jti
| Vereist | 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
|
...
Excerpt |
---|
name | JSON Web Token (JWT) 4 |
---|
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOETEN een getekende JWT maar één keer accepteren
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| 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
|
|
...
Excerpt |
---|
name | JSON Web Token (JWT) 5 |
---|
|
Panel |
---|
panelIconId | 2705 |
---|
panelIcon | :white_check_mark: |
---|
panelIconText | ✅ |
---|
bgColor | #FFF0B3 |
---|
| DSGO.Basis : Partijen MOGEN gebruik maken van JWE als beschreven in RFC 7516
|
|
...