Sikkerhetskrav for klienter og API-er som integerer med HelseID
Dette dokumentet inneholder standardene som kreves for enhver programvare som skal ta i bruk HelseID-tjenesten.
| Termer | |
|---|---|
| HelseID | En autorisasjonstjener, som beskrevet i RFC 6749. Blir brukt til å sikre nasjonale API-er for helsesektoren. |
| Klient | En klient (client) som definert i RFC 6749. I kontekst av HelseID er en klient en programvareinstallasjon som følger denne sikkerhetsprofilen. |
| Konfidensiell klient | Konfidensielle klienter er klienter som har mulighet til å opprettholde konfidensialiteten til en klienthemmelighet. Alle klienter som bruker HelseID må autentisere seg med denne hemmeligheten. Enhver klient som bruker HelseID må være en konfidensiell klient. |
| JWT | JSON Web Token er en åpen standard (RFC 7519) som definerer en kompakt og selvstendig måte for sikker overføring av informasjon mellom parter som et JSON-objekt. Informasjonen kan bli verifisert som gyldig ettersom den er signert digitalt. |
| Klientautentisering | Prosessen der en klient beviser sin identitet til autorisasjonstjeneren. I HelseID blir dette alltid gjort med å signere en JWT med en privatnøkkel, slik at denne privatnøkkelen korresponderer med en offentlig nøkkel som finnes registrert i HelseID. |
| Eksternt API | Et API som er sikret med HelseID. |
| Internt API | Et API som bare er tilgjengelig for enheter inne i klientens programvare. |
| Nøkkelord | Nøkkelordene må, må ikke, skal, skal ikke, bør, og kan i dette dokumentet må tolkes slik som nøkkelordene must, must not, shall, shall not, should, og may i RFC2119. |
Sikkerhetskrav krav for alle HelseID-klienter
SK1: Alle klienter skal bare etablere forbindelser til tjenere, inkludert HelseID, med bruk av TLS. Alle TLS-forbindelser skal settes opp med bruk av TLS 1.2 eller høyere, og skal bruke RFC 7525. Klienter bør bruke TLS 1.3. Intern trafikk i klientens nettverk bør også sikres med TLS.
SK2: Alle klienter skal gjennomføre klientautentisering med bruk av private_key_jwt, som beskrevet i Bruk av client assertion for klientautentisering i HelseID. Se Krav til kryptografi for algoritmer som HelseID vil godkjenne.
Utløpstiden (exp-claimet) i client_assertion skal ikke bli satt til mer enn 10 sekunder i fremtiden.
SK3: Alle klienter må være konfidensielle klienter, og den offentlige nøkkelen til klienthemmeligheten må være kjent for HelseID før klientautentiseringen skal gjennomføres. Web-applikasjoner uten backend (kun frontend-kode) er ikke godtatt for bruk med HelseID.
SK4: En klient må beskytte konfidensialiteten og integriteten til hemmeligheten som brukes til klientautentisering; bare programvaren skal ha tilgang til hemmeligheten. Så lenge klienthemmeligheten er tilstrekkelig godt beskyttet, vil HelseID også godta programvare for tykklienter som konfidensiell klient.
Klienthemmeligheten kan bli delt mellom flere komponenter som deler grensene til programvaren. See Håndtering av hemmeligheter i distribuerte systemer for ytterligere informasjon.
SK5: Hemmeligheten som brukes til klientautentisering skal bare brukes for
- autentisering av en enkelt klient mot HelseID, og
- lage et DPoP-bevis til HelseID-tjeneren og API sikret med HelseID som krever DPoP
SK6: Hvis en klient vil konsumere et API, må klienten ha funksjonalitet til å ta i bruk token som er bundet til senderen med bruk av «Demonstrating Proof-of-Possession at the Application Layer» (DPoP), som beskrevet her. DPoP-bevis må formateres som beskrevet i vedlegget Formatering av DPoP-bevis. Dette kravet gjelder også når API-et ikke har etablert støtte for DPoP ennå.
SK7: Alle klienter skal sende Access-token i http-autorisasjonsheadere, som beskrevet i RFC 6750, Bearer Token Usage, eller ved å bruke RFC 9449, DPoP. Access-token skal ikke bli eksponert i en URL og skal ikke gjøres tilgjengelige for sluttbruker.
SK8: Klienter skal ikke eksponere innholdet i tokens til sluttbrukeren på noe slags vis. Dette betyr at web-klienter må implementere en integrasjon mot HelseID i backenden.
SK9: Ethvert internt API som trenger å konsumere et eksternt API som er sikret med HelseID må også følge denne sikkerhetsprofilen. Dette betyr at et internt API ikke kan sikres med andre autentiseringsmekanismer enn de som HelseID tillater. For eksempel vil bruk av «shared secret» (client_secret) ikke kunne godtas hvis API-et vil ha tilgang til et eksternt (nasjonalt) API som er sikret med HelseID.
SK10: Klienter skal være oppdatert med tiltak for å håndtere de mest kjente sikkerhetsrisikoene i henhold til OWASP Top Ten.
Sikkerhetskrav for klienter som trenger brukerinnlogging
Kravene er en utvidelse av de generelle kravene for alle HelseID-klienter.
SB1: Klienter skal bruke «Authorization Code Flow» som beskrevet i OpenID Connect specification.
Parameteren response_type må ha verdien code, andre verdier vil bli avvist.
SB2: Klienter skal bruke «Proof Key for Code Exchange» (PKCE), som beskrevet i RFC 7636, for å minske muligheten for koder på avveie og andre kjente angrep. Klienter må bruke verdien S256 for parameteren code_challenge_method. Verdien i parameteren code_challenge, må være unik for hver forespørsel, som beskrevet i RFC 7636.
SB3: Klienter må bruke mekanismen «Pushed Authorization Requests» (PAR) for å ikke sende mer informasjon gjennom nettleseren enn nødvendig. Dette er beskrevet i RFC 9126.
SB4: Klienter skal validere ID-tokenet fra HelseID i henhold til disse reglene.
SB5: En klient som gjennomfører en lokal brukerinnlogging (f.eks. brukernavn/passord mot lokal brukerdatabase, innlogging i lokalt domene) i tillegg til brukerinnlogging gjennom HelseID, skal validere at begge brukeridentiteter tilhører den samme personen.
Valideringen gjøres ved enten å sammenligne pid-claimet (fødselsnummer) eller HPR-nummer-claimet til korresponderende informasjon på den lokale brukeridentiteten.
Sikkerhetskrav for klienter som ikke trenger brukerinnlogging
Kravene er en utvidelse av de generelle kravene for alle HelseID-klienter.
SC1: Klienter må bruke «Client Credentials Grant», som beskrevet i RFC 6749.
Sikkerhetskrav for API-er som skal sikres med HelseID
SA1: Et API-endepunkt skal bare akseptere Access-tokens. Andre mekanismer, som for eksempel API-nøkler, kan kun bli brukt på separate endepunkter.
SA2: API-et må validere Access-tokens som spesifisert i vedlegget Validering av Access-token.
SA3: API-et må tilby et endepunkt som støtter DPoP.
SA4: API-et må validere DPoP-bevis som spesifisert i vedlegget Validering av DPoP-bevis.
SA5: Eksisterende API-er kan også tilby et separat endepunkt som bruker Bearer-tokens for å være bakoverkompatibel med gamle klienter.
- API-et skal ikke akseptere både Bearer-tokens og DPoP-tokens på det samme endepunktet.
- API-et må bruke ulike scopes per endepunkt for å sikre at DPoP- og Bearer-tokens ikke kan brukes om hverandre.
SA6: Nye API-er skal ikke støtte Bearer-tokens.
SA7: API-er skal være oppdatert med tiltak for å håndtere de mest kjente sikkerhetsrisikoene i henhold til API Security Top Ten fra OWASP.