This page in English no

Sikkerhetsprofil for HelseID-klienter og API-er

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.
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.
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.
Eksternt API Et åpent 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, and kan i dette dokumentet må tolkes slik som nøkkelordene must, must not, shall, shall not, should, og may i RFC2119.

Med unntak av et par forskjeller, som er lagt til for å gjøre det enklere å bruke HelseID i helsesektoren, er sikkerhetsprofilen til HelseID nært knyttet til FAPI 2.0-profilen. Forskjellene er som følger:

  • HelseID tillater at en lokalt installert tykklient kan bli sett på som en konfidensiell klient
  • MTLS for klientautentisering er ikke støttet
  • Forespørsler uten PAR vil bli godtatt for klienter som allerede er i bruk
  • "Consent" (samtykke for bruk av HelseID for innlogging) blir ikke brukt

Generelle krav for alle HelseID-klienter

  • Klienter må bruke et sertifisert OAuth2- eller OpenID Connect-klientbibliotek hvis et slikt er tilgjengelig for det brukte programmeringsspråket. HelseID-teamet kan bidra med veiledning for bruk av bibliotek.

  • 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.

  • Klienter skal gjennomføre klientautentisering med bruk av private_key_jwt, som beskrevet i OpenID Connect-spesifikasjonen. Se dette dokumentet for godkjente algoritmer.

  • Klienter skal 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.

  • Hemmeligheten som brukes til klientautentisering skal bare brukes for

    • autentisering av en enkelt klient, og
    • lage et DPoP-bevis til HelseID-tjeneren og API sikret med HelseID som krever DPoP

  • Klienten 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.

  • Klienter må bruke informasjon fra HelseIDs metadata-endepunkt i stedet for å hardkode URL-er for endepunkt og andre konfigurasjonsverdier. Metadata-endepunktet vil alltid være tilgjengelig på https://helseid-sts.nhn.no/.well-known/openid-configuration.

  • Hvis en klient vil konsumere et API som har et DPoP-aktivert endepunkt, 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 i RFC9449. DPoP-bevis må formateres som beskrevet i vedlegget Formatering av DPoP-bevis. Se dette dokumenet for mer informasjon.

  • Klienter skal sende Access-token i http-autorisasjonsheadere, som beskrevet i RFC 6750, Bearer Token Usage, eller ved å bruke RFC 9449, DPoP. Access-token må ikke bli eksponert i en URL.

  • Klienter skal aldri eksponere innholdet i tokens til sluttbrukeren på noe slags vis. Dette betyr at web-klienter må implementere en integrasjon mot HelseID i backenden.

  • 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.

Krav for maskin-til-maskin-klienter

Krav for klienter som trenger brukerinnlogging

  • Disse kravene er en utvidelse av de generelle kravene for alle HelseID-klienter.

  • Klienter skal bruke «Authorization Code Flow» som beskrevet i OpenID Connect specification.

  • 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 S256 code_challenge_method. Verdien i code_challenge parameteret, må være unik for hver forespørsel, som beskrevet i RFC 7636.

  • Alle nye klienter må bruke mekanismen «Pushed Authorization Requests» (PAR) for å unngå å sende unødvendig informasjon gjennom nettleseren. Dette er beskrevet i RFC 9126.

  • Hvis klienten trenger å sende fingranulert autorisasjonsinnhold til HelseIDs /authorize-endepunkt, skal den bruke authorization_details-strukturen, som definert i RFC9396.

  • Hvis klienten trenger å sende fingranulert autorisasjonsinnhold til HelseIDs Token-endepunkt, skal den bruke assertion_details-strukturen.

  • Klienter skal validere iss-parameteret i token fra HelseID for å unngå «mix-up» angrep.

  • Klienter skal validere ID-tokenet fra HelseID i henhold til disse reglene.

  • Klienten skal ikke bruke Access-tokenet for tilgangskontroll. Access-tokenet skal ikke inspiseres av klienten, og må sees på som ugjennomsiktig for klienten.

  • En klient som gjennomfører en lokal brukerinnlogging i tillegg til brukerinnlogging gjennom HelseID, skal validere at begge brukeridentiteter tilhører den samme personen. Dette gjøres bed enten å sammenligne pid-claimet (fødselsnummer) eller HPR-nummer-claimet til korresponderende informasjon på den lokale brukeridentiteten.

  • Klienter skal gjennomføre beskyttelse mot XSS- og CSRF-angrep. Se eksterne kilder som for eksempel OWASP for detaljer om hvordan du kan sikkerhetsteste og sikre en klient.

  • Klienter skal ikke gjøre redirectors tilgjengelige der klienten er sårbar for ondsinnet redirigering.

  • Klienter skal beskytte mot angrep med bruk av HTTP-header

  • Klienter skal beskytte mot angrep via JavaScript (for eksempel XSS-angrep)

Krav for API-er som skal sikres med HelseID

  • API-et må bruke et sertifisert OAuth2-bibliotek for tokenvalidering hvis et slikt er tilgjengelig for det brukte programmeringsspråket. HelseID-teamet kan bidra med veiledning for bruk av bibliotek.

  • Et API-endepunkt skal bare akseptere Access-tokens. Andre mekanismer, som for eksempel API-nøkler, kan kun bli brukt på separate endepunkter.

  • API-et må validere Access-tokens som spesifisert i vedlegget Validering av Access-token.

  • API-et må tilby et endepunkt som som støtter DPoP.

  • API-et kan også tilby et separat endepunkt som bruker Bearer-tokens for å være bakoverkompatibel med gamle klienter. Et API skal ikke akseptere både Bearer-tokens og DPoP-tokens på det samme endepunktet. Hvis denne mekanismen blir tatt i bruk, må API-et bruke ulike scopes per endepunkt for å sikre at DPoP- og Bearer-tokens ikke kan brukes om hverandre.

  • API-et må validere DPoP-bevis som spesifisert i vedlegget Validering av DPoP-bevis.

Generell informasjon for API-sikring

Se denne sjekklisten for retningslinjer om hvordan du vil sikre API-et ditt.