...
Guidelines for using JSON Web Tokens (JWTs)
Bruk av Using JSON Web Tokens (JWTs) for å sikre APIs er en to secure your APIs has become an ad-hoc standard i in the IT-bransjen i dag. Men de underliggende konseptene og mekanismene kan være komplekse og blir ofte misforstått.
Generelle råd for bruk av JWTs
...
Å bruke JWTs for sesjoner introduserer risiko. Gjennomfør alltid en grundig risikovurdering før du ruller ut til ditt produksjonsmiljø.
...
JWTs forutsetter at hemmeligheter håndteres på ordentlig måte i API-klienter og i API. Hemmeligheter kan være både passord og kryptografisk nøkkelmateriale. Sørg for å lagre nøkkelmaterialet ditt på en trygg måte!
...
industry. However, the underlying concepts and mechanisms can be complex and are often misunderstood.
General advice when using JWTs
Using JWTs to handle sessions introduces new risks. Allways do a thorough risk assessment before you deploy to your production environment.
Using JWTs assumes that all involved secrets are handled in a proper way in both API-clients and APIs. Secrets could be both passwords and cryptographic key material. Always make sure your secrets are kept safe!
Do not accept unsafe JWTs with the JOSE header {"alg": none; }. JWTs skal alltid være signerte og bruke et gyldig og riktig signaturskjema
Dersom en JWT inneholder sensitive data skal det være kryptert
Ting å tenke på i forbindelse med Access Tokens
Et "self contained" JWT kan ikke revokeres før gyldigheten utløper. Vurder å kreve bruk av referansetokens dersom tokenet gir tilgang til sensitive eller kritiske data.
Access Tokens skal ha så kort levetid som mulig - som en generell regel kan vi si at levetiden skal være være kortere dess mer sensitive data et API eksponerer
For å forbedre brukeropplevelsen bør sesjoner med lang levetid kombineres med Access Tokens som har kort levetid. Dette kan oppnåes ved å bruke refresh tokens på klientsiden.
Alltid verifiser en JWTs integritet
Du må alltid validerere signature til tokenet
Alltid bruk bibliotek og rammeverk som validerer signaturen til tokenet
HelseID tilbyr bare bruk av asymetriske signaturershould always be signed and should use a valid and correct signature scheme
If a JWT contains sensitive data it should be encrypted
Things to consider when using Access Tokens
A "self contained" JWT can not be revoked until it expires. Consider using referenced tokens if the token provides access to sensitive or high-risk data.
Access Tokens should have a life-time that is as short as possible - as a general principle the life-time should be shorter the more sensitive data an API exposes (TODO: forbedre setningen)
To enhance the user experience sessions with a long life-span should be combined with Access Tokens that have short life-span. You can acheive this by using refresh tokens on the client.
Always verify the integrity of the JWT
Always validate the token signature
Make sure your libraries and frameworks always validates the token signature
HelseID only offers signatures based on asymmetric algorithms
Alltid valider påstander (claims) i access tokenet
Du må alltid sjekke påstanden Always verify the "exp" for å sikre at tokenet ikke har utløpt
Du må alltid sjekke påstanden "nbf" for å sikre at tokenet faktisk er "aktivt"
Du må alltid sjekke påstanden "iss" for å sikre at utstederen av tokenet er noen du har tillit til
Du må alltid sjekke påstanden "aud" for å være sikker på at tokenet er ment for deg
Dersom "aud" claim ikke er tilstede i tokenet må du avvise JWTen
Dersom du bruker "scope" for tilgangsstyring må du alltid verifisere at verdiene i claimet er riktige.
Alltid valider og verifiser at verdien i claimet "security_level" stemmer overens med kravene for ditt API.
Alltid valider og verifiser at verdien i claimet "pid" er gyldig.
Alltid valider og verifiser at veriden i claimet "hpr_nr" er gyldig.
Alltid valider og verifiser at verdien i claimet "orgnr" er gyldig.
IKKE STOL PÅ PÅSTANDER
“kid” - ikke gjør sertifikatforespørsler før verdiene er validert
“jku” eller “x5u” er headerverdier som peker på en URL. Ikke følg URLene før de er validert for å unngå SSRF angrepclaim to make sure the token hasn’t expired
Always verify the claim "nbf" to make sure the token actually is "active"
Always verify the claim "iss" to make sure that the token issuer is someone you actually trust
Always verify the claim "aud" to make sure that the token is intended for you
Reject the request if the "aud" claim is missing
If you use "scopes" for access control you must always make sure that the values in the “scope” claims are valid and correct.
Always validate and verify that the value in the claim "security_level" corresponds with the requirements for your API.
Always validate and verify the value in the claim "pid".
Always validate and verify the value in the claim "hpr_nr".
Always validate and verify the value in the claim "orgnr".
DO NOT BLINDLY TRUST THE VALUE IN CLAIMS
“kid” - do not perform certificate requests before the values are validated and verified
“jku” or “x5u” are header values that point to a URL. Do NOT follow these URLs before they are validated in order to avoid SSRF attacks