Client Development

Owned by Andreas Martin Saxegaard (Unlicensed)
Last updated: Mar 07, 2023 by Dag Østerhagen
5 min read

Her finner du eksempel og hjelp til å konfigurere din applikasjon til å autentisere dine brukere via HelseID

En av oppgavene HelseID kan hjelpe deg med er autentisering av dine brukere. Selve autentiseringen skjer hos en av våre tilknyttede identitetstilbydere, og blir utført ved hjelp av forskjellige teknikker; for eksempel brukernavn/passord kombinasjon eller en sertifikatbasert pålogging. I noen tilfeller må brukeren også presentere en andre-faktor, for eksempel via SMS, en mobil app eller en FIDO2 brikke.

Du kan lese litt mer om de forskjellige mekanismene som brukes for å autentisere personer samt sikkerhetsnivåene de gir på sidene om grunnleggende kunnskap.

Klientbibliotek og mellomvare

Du skal aldri skrive sikkerhetskode selv. HelseID anbefaler at du alltid bruker klientbibliotek og mellomvare som er utviklet av profesjonelle sikkerhetsfolk. 

OpenId Connect tilbyr et sertifiseringsprogram og fører en oversikt over klientbibliotek og mellomvare som både er sertifisert og ikke sertifisert. Du finner oversikten her.

HelseID-kjernekomponent

HelseID bruker et rammeverk som heter IdentityServer4. IdentityServer4 er basert på åpen kildekode som ligger tilgjengelig på GitHub. På sidene deres finner du utfyllende dokumentasjon som beskriver de tekniske detaljene i IdentityServer4, men også en beskrivelse av hvordan du kan implementere autentisering av brukere i din applikasjon.

I tillegg har utviklerne av IdentityServer4 tilgjengeliggjort kodebibliotek med forskjellige praktiske eksempler på implementasjon av IdentityServer4, samt hvordan man implementerer autentisering i forskjellige typer klienter. Kodeeksemplene for klienter finner du her og her (IdentityServer3), under mappene som heter "Clients" (IdentityServer4, IdentityServer3).

OpenId Connect

HelseID tilbyr autentisering ved bruk av OpenId Connect protokollen. Protokollen er bygd på topp av rammeverket OAuth 2.0 og utgjør et identitetslag som lar applikasjoner verifisere identiteten til sluttbrukeren. Du vil kjenne igjen mange av begrepene i OpenId Connect når du leser OAuth 2.0 spesifikasjonen.

All autentisering av brukere starter med at din applikasjon retter en forespørsel om autentisering av bruker til HelseID. HelseID overtar deretter prosessen, og returnerer til slutt et spesielt token som kalles et ID token.

ID Token

OpenId Connect spesifikasjonen innførte en ny type token som kalles ID Token. Spesifikasjonen sier at dette tokenet skal være en JWT (Json Web Token). Et JWT token inneholder et sett av claims (påstander) i JSON format, og skal være kryptografisk signert og/eller kryptert.

I tillegg til standard claims som er definert i spesifikasjonene av JWT og OpenId Connect vil et ID Token kunne inneholde annen informasjon om brukeren, som f.eks fødselsnummer og hpr nummer. På sidene som inneholder Teknisk Dokumentasjon kan du se hvilke claims HelseID tilbyr. 

ID Tokenet er et anliggende mellom applikasjonen som ber om autentisering av brukeren (klienten) og HelseID, og skal i utgangspunktet ikke benyttes til andre formål enn å la klienten få tilgang til informasjon om den autentiserte brukeren.

Innholdet i ID Tokens

Det kan være fristende å legge annen informasjon om brukeren inn i et token som er signert av en sentral autoritet, men i dette tilfellet ønsker HelseID å være restriktive. Vi vil unngå å legge sensitiv informasjon i tokens generelt, og mener at applikasjoner og tjenester bør finne andre måter å representere informasjon som ikke direkte er knyttet opp til personers identitet.

Forespørsel om autentisering

En forespørsel om å autentisere en bruker starter alltid ved at din applikasjon gjør en HTTP Request mot en adresse hos HelseID. Denne forespørselen skal være formatert på en spesifikk måte, og skal alltid inneholde følgende informasjon som parametre i forespørselen:

  • response_type
    Dette parameteret angir hvilken grant type (autentiseringsflyt) du ønsker å bruke. Les mer om dette i avsnittet som heter Autentiseringsflyt (aka grant type) under.

  • scope="openid"
    Dette parameteret med verdien openid MÅ alltid være med i en gyldig OpenId Connect forespørsel. Les mer om scopes i eget avsnitt under

  • redirect_uri
    Dette parameteret angir adressen som HelseID skal sende responsen med id tokenet til. Når brukeren er autentisert vil forespørselen omdirigeres til verdien du har angitt i dette parameteret. Verdien må være en gyldig URI, og må være registrert i din klientkonfigurasjon i HelseID. 

Det finnes mange andre parametre som kan være med i en forespørsel om autentisering, men de er ikke påkrevd, og vil variere litt avhengig av hvilken autentiseringsflyt du ønsker å benytte. Du kan se en liste over alle mulige parametre i spesifikasjonen av OpenId Connect.

Autentiseringsflyt (aka grant type)

OpenId Connect definerer et sett av det som kalles grant types, eller autentiseringsflyt. En grant type beskriver forskjellige autentiseringsflyter, og er laget for å støtte ulike scenario basert på applikasjonstyper og teknologiplattformer.

De tre autentiseringsflytene som OpenId Connect beskriver er:

  • Implicit Flow

  • Authorization Code Flow

  • Hybrid Flow

Du angir hvilken flyt du ønsker å bruke ved å sende inn en verdi eller kombinasjon av verdier i parameteret response_type i autentiseringsforespørselen mot HelseID. Verdiene i response_type kan være: "id_token", "token" og "code", og flytene kan kombineres på følgende måte for å angi hvilken flyt du ønsker:

  • Implicit Flow : "id_token", "id_token token"

  • Authorization Code Flow: "code"

  • Hybrid Flow: "code id_token", "code token" eller "code id_token token"

Det som skiller disse forskjellige flytene er hvordan tokens blir returnert til klienten, da enten via front-kanal (nettleser), og bak-kanal (eget http kall til STS). Når du bruker Implicit flow vil tokenet flyte via front-kanal, mens Hybrid Flow er en kominasjon slik at ID Tokenet flyter via front-kanal, mens Access Tokens flyter via bak-kanal.

Du kan lese mer om dette i spesifikasjonen av OpenId Connect.

Scopes

OAuth 2.0 introduserte konseptet scopes for å angi tilgang til en ressurs i form av et API. OpenId Connect har lånt begrepet fra OAuth 2.0, men bruker det på en litt annen måte. OpenId Connect bruker scopes for å angi en ønsket identitetsressurs. For identitetsressurser i HelseID vil et angitt scope bety at man får ett eller flere claims i ID Tokenet.

Forskjellen i bruken av scopes mellom OAuth og OpenId Connect kan være forvirrende, spesielt dersom man både bruker OpenId Connect og OAuth 2.0 mekanismene.

Du ber om ett eller flere scopes ved å sette en verdi på parameteret scopes i forespørselen til HelseID.  For eksempel vil det forespurte scopet helseid://scopes/hpr/hpr_number bety at ID Tokenet inneholder et claim som har navnet helseid://claims/hpr/hpr_number og den autentiserte personens hpr nummer som verdi.

For å autentisere brukere ved bruk av OpenId Connect MÅ du angi ett spesielt scope som har verdien "openid". Men, HelseID tilbyr også flere scopes som beriker ID Token med mer informasjon om brukeren. Du kan lese mer om hvilke scopes vi tilbyr i HelseID i vår tekniske dokumentasjon.

Applikasjonstyper og autentiseringsflyt

Vi har laget noen beskrivelser av hvordan man autentiserer brukere med HelseID med utgangspunkt i hvilken type applikasjon du lager.

Serverapplikasjoner

Med serverapplikasjoner mener vi web-applikasjoner som kjører på en server. Et eksempel på en slik applikasjon er f.eks en applikasjon utviklet i Microsoft .Net MVC.

Tykke klienter

Med tykke klienter mener vi applikasjoner som installeres og kjøres lokalt på en datamaskin. Eksempler på dette er Microsoft .Net WPF eller Winforms.

Mobile apps

Med mobile apps mener vi program som installeres og kjøres på mobiltelefoner. Eksempler på dette er apps laget i Xamarin eller programmert spesifikt for iOS eller Android.

Javascript-baserte applikasjoner

Med Javascript-baserte applikasjoner mener vi program som lastes ned lokalt og kjører i nettleseren. Eksempler på dette er applikasjoner som er utviklet i ett rammeverk som f.eks Angular, React eller lignende, men også rene javascriptapplikasjoner.