Dette dokumentet inneholder retningslinjer som vil hjelpe utviklere med å lage og konsumere API på en sikker måte.
Retningslinjene er inspirert av dokumentet "OWASP cheat for REST Security" som finnes her : https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html.
Generelle retningslinjer for sikring av REST baserte API
Sikre alle endepunkt med HTTPS. Dette vil blant annet beskytte Access Tokens som overføres mellom HelseID og API-klient, og API-klient og API endepunkter.
Utfør tilgangskontroll på hvert endepunkt, selv om APIet skjuler seg bak en API Gateway.
Krev bruk av JWTs som sikkerhetsbillett.
Begrens hvilke HTTP metoder som er i bruk. Avslå alle HTTP metoder som ikke er i bruk ved å svare med HTTP statuskode 405 - "method not allowed"
Valider alle inputparametre
Aldri stol på input parametre, se gjerne på OWASP sitt Input Validation cheat sheet for mer detaljerte forklaringer
Valider input-verdiens lengde, gyldige verdier, format og type
Alle inputparametre skal ha sterk typing
Ikke godta uventet eller ulovlig innhold
Bruk bibliotek eller rammeverk for vasking av inputverdier
Definer grenser for aksepterte datamengder i forespørsler og avslå forespørsler som er for store ved å svare med HTTP statuskode 413 - "Request Entity Too Large"
Loggfør feil som oppstår i forbindelse med inputvalidering, vurder om regler som låser ute klientapplikasjoner som feiler for ofte implementeres bør implementeres
Valider "content types". Dersom du ikke validerer "content type" åpner du for injisering og eksekvering av kode
Valider "content types" for innkommende kall til ditt API
Avslå innkommende kall som enten mangler "content type", eller som inneholder "content type" verdier som ikke er forventet. Svar på slike forespørsler med HTTP statuskode 406 - "Unacceptable" eller 415 - "Unsupported Media Type".
Unngå uforvarende eksponering av content types som ikke er bruk ved å definere eksplisitte content types. Ved å gjøre dette unngås angrep ved XXE.
Svar med trygge content types
IKKE kopier "Accept" header til "Content-type" headeren til responsen
Ikke godta forespørselen dersom "Accept" headeren ikke inneholder en av de tillatte typene. Svar med HTTP statuskode 406 - "Not Acceptable" dersom typen angitt i "Accept" headeren ikke er tillatt.
Sørg for at "content type" headere i din response stemmer overens med innholdet i body.- F.eks application/json og ikke application/javascript
Unngå eksponering av endepunkt for administrasjon via internett
Vær varsom med feilhåndtering
Svar med generiske feilmeldinger - unngå å avsløre detaljer om feilsituasjonen dersom det ikke er nødvendig
Ikke vis tekniske detaljer som "call stacks" eller intern informasjon til klientapplikasjonen
Sikkerhetsheadere
Send "Content-Type" headeren med riktig content type og charset.
Send sikkerhetsheaderen "X-Content-Type-Options: nosniff" for å sikre at nettleseren ikke forsøker å sette en annen Content-Type enn det som faktisk ble sendt (dette kan føre til XSS).
Send sikkerhetsheaderen "X-Frame-Options: deny" for å beskytte mot "drag'n drop clickjacking" angrep i eldre nettlesere
Riktig bruk av CORS. Ved å levere passende CORS headere signaliserer REST APIet ditt hvilke domener (origins) som har lov til å gjøre JavaScript kall til REST-tjenesten
Deaktiver CORS headere hvis kall på tvers av domener ikke støttes eller forventes
Vær så spesifikk som mulig, og så generell som nødvendig når du definerer hvilke origins som er gyldige for kall på tvers av domener
Sørg for at dine API alltid sender riktige HTTP response koder
Retningslinjer for bruk av JSON Web Tokens (JWTs)
Bruk av JSON Web Tokens (JWTs) for å sikre APIs er en ad-hoc standard i 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, både passord og kryptografisk nøkkelmateriale. Sørg for å lagre nøkkelmaterialet ditt på en trygg måte!
Ikke aksepter usikrede JWTs med 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 signaturer
Alltid valider påstander (claims) i access tokenet
Du må alltid sjekke påstanden "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 angrep