Autentiseringsflyt

Før EPJ kan opprette en sesjon i Kjernejournals innloggingsløsning må den ha en aktiv sesjon med DPoP, se HelseID sin dokumentasjon på bruk av DPoP. Alle backendkall mot Kjernejournal innlogging krever autentisering med DPoP.

API'et krever at DPoP-bevisene inneholder en jti som er en Base64Url enkoding av minst 96 pseudorandom bits, etter anbefalingen i RFC 9449. Vi anbefaler å bruke f.eks. en UUID som grunnlag, i java kan dette gjøres med f.eks. biblioteket Nimbus:

import java.util.UUID;
import com.nimbusds.jose.util.Base64URL;

Base64URL jti = Base64URL.encode(UUID.randomUUID().toString());

Denne siden beskriver autentiseringsflyten. Den består av følgende deler:

• Opprettelse av sesjon
• Vedlikehold av sesjon
• Avslutte sesjon
• Bytte av pasient

Helseindikator

Hvis man ønsker å vise helseindikator, så kan man gjøre det i kombinasjon med flyten definert under. Merk at det er et helt uavhengig steg som man valgfritt kan gjøre. Se egen dokumentasjon.

Krav for alle endepunkter i innloggingstjenesten

Dette er krav som gjelder for endepunktene session/create, session/refresh og session/end

HelseID Access token

Tjenesten krever et brukerbasert HelseID-token med følgende claims:

Headere

Alle endepunktene krever følgende headere:

Opprettelse av Kjernejournal Innlogging-sesjon

For å åpne Kjernejournal portal med tillitsrammeverket til HelseID, så må EPJ:

• Hente access token fra HelseID
• Opprett Kjernejournal Innlogging-sesjon ved å sende access token til Kjernejournal Innlogging
  • Man får en kode tilbake
• Åpne Kjernejournal Portal med koden

Begreper:

• HelseID-tokens
  • EPJ ber om access tokens med tillitsrammeverket
  • De kobler sammen brukeren og hvilken relasjon brukeren har til pasienten
• Kjernejournal Innlogging-sesjon
  • Innlogging-sesjonen krever et HelseID access-token, en pasient-id og et samtykkegrunnlag (access_basis)
  • Innlogging-sesjonen brukes for åpne en websesjon mot Kjernejournal Portal

Detaljert flyt

Her følger en detaljert forklaring, med henvisning til tallene i sekvensdiagrammet over.

1. Hent HelseID-tokens med tillitsrammeverk
   • Dette er en forenkling, se HelseID-dokumentasjonen for detaljer
   • Tillitsrammeverket er dokumentert her
2. Access token med tillitsrammeverk-claim
3. Generer par av ehr_code_challenge, ehr_code_verifier
   • For å koble Innlogging-sesjonen til en websesjon i Kjernejournal Portal så brukes et challenge og verifier-par.
   • Det følger Proof Key for Code Exchange-standarden fra OAuth (RFC 7636).
   • ehr_code_verifier skal være en kryptografisk tilfeldig streng med fra 43 til 128 karakterer, bestående av A-Z, a-z, 0-9, i tillegg til karakterene -._~ (bindestrek, punktum, understrek, og tilde). Denne skal sendes som en queryparameter ved kall i nettleser.
   • ehr_code_challenge skal være en Base64-URL-encodet streng av SHA256 hashen til ehr_code_verifier. Denne skal sendes ved opprettelse av sesjonen.

Her er eksempel på hvordan man kan generere verdiene med Nimbus-biblioteket i Java.

import com.nimbusds.oauth2.sdk.pkce.CodeChallenge;
import com.nimbusds.oauth2.sdk.pkce.CodeChallengeMethod;
import com.nimbusds.oauth2.sdk.pkce.CodeVerifier;

CodeVerifier ehrCodeVerifier=new CodeVerifier();
CodeChallenge ehrCodeChallenge=CodeChallenge.compute(CodeChallengeMethod.S256,ehrCodeVerifier);

4. Opprett Kjernejournal Innlogging-sesjon
   • Før man kan åpne Kjernejournal Portal, så må man opprette en sesjon i Kjernejournal Innlogging.

• Header: Authorization
  • HelseID DPoP Access token fra steg 2
• Header: DPoP
  • DPoP-signatur, se HelseID
  • Merk at DPoP-signaturen har kort levetid, så sørg for at klokken på maskinen som genererer signaturen er i synk.
• Header: X-SOURCE-SYSTEM
  • Påkrevd header
  • Fritektsfelt for å identifiere kildesystemet i logger
• Body: patient_identifier
  • Pasientens fødselsnummer eller D-nummer
  • Se tabell under
• Body: access_basis
  • Grunnlag for tilgang til helseopplysninger i nasjonal kjernejournal
  • Se tabell under
• Body: practitioner_authorization
  • Gjeldende autorisasjon for helsepersonellet. Valideres mot Helsepersonellregisteret.
  • Dersom authorization er til stede i attest, må den være lik practitioner_authorization
  • Se tabell under

Grunnlag (access_basis)

Access basis indikerer grunnlag for tilgang til helseopplysninger i nasjonal kjernejournal. Hvilke regler som gjelder er definert i kjernejournalforskriften

Dersom unntak av samtykke for brukeren ikke kan direkte avledes under oppretting av innlogging-sesjon, så må brukeren presenteres med et valg av samtykke i EPJen ved åpning av Kjernejournal.

Beskrivelse av samtykke-verdier

Her er eksempel på hvordan man kan presentere valg av samtykke i EPJ til brukeren før man åpner Kjernejournal:

Pasientidentifikator (patient_identifier)

Pasientens identifikator kan representeres gjennom ulike systemer med forskjellige autorative kilder.

Autorisasjon (practitioner_authorization)

Gjeldende autorisajon for helsepersonellet, denne valideres mot Helsepersonellregisteret.

Dette er et eksempel på en request:

POST /api/session/create
Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...
DPoP: aseqwe231asSD...
X-SOURCE-SYSTEM: EPJ-System, (v1.2.3-RC)
Content-Type: application/json

{
  "ehr_code_challenge": <Verdien av challenge generert i steg 3>,
  "claims": {
    "patient_identifier": {
      "id": <fødselsnummer>,
      "system": "urn:oid:2.16.578.1.12.4.1.4.1",
      "authority": "https://www.skatteetaten.no"
    },
    "access_basis": {
      "code": "AKUTT",
      "system": "urn:oid:2.16.578.1.12.4.5.11.1",
      "assigner": "https://nhn.no"
    }
    "practitioner_authorization": {
      "code": "LE",
      "system": "urn:oid:2.16.578.1.12.4.1.1.9060",
      "assigner": "https://www.helsedirektoratet.no/"
    }
  }
}

5. Opprett sesjon-respons

   • Ved suksess, så får man en respons tilbake som inneholder en code og en sessionId
   • sessionId trengs for å kunne vedlikeholde og avslutte Kjernejournal Innlogging-sesjonen (se senere kapittel)
   • code trengs i neste steg, for å åpne Kjernejournal Portal-siden

6. Åpne nettside hentpasient

   • Åpne hentpasient.html-siden i Kjernejournal Portal
     • Eksempel for Systemtest 1: https://st1.kjernejournal-test.no/hpp-webapp/hentpasient.html?code=...&ehr_code_verifier=...
   • Krever to request parameter som identifiserer Innlogging-sesjonen
     • code fra responsen i steg 5
     • ehr_code_verifier fra steg 3

7. Sesjonen har blitt opprettet og Kjernejournal portal kan vises i nettleseren

Vedlikehold Kjernejournal Innlogging-sesjon

Før HelseID-access tokenet utløper må EPJ hente nytt token fra HelseID og sende det til Kjernejournal Innlogging-tjenesten. Tokenet vil bli brukt for å autentisere helsepersonellets aktivitet i kjernejournal. Konsekvensen av å ikke fornye tokenet i tide er at sesjonen i kjernejournal blir avsluttet.

For å sørge for en god brukeropplevelse for helsepersonell bør innsendt token ha et stort nok overlapp med forrige token ved å fornye tokenet før det forrige tokenet går ut. Vi anbefaler at dette overlappet er konfigurertbart fra EPJ og er på minst 5 sekunder. Konsekvensen av for kort overlapp er at helsepersonellet kan oppleve ustabilitet.

Detaljert flyt

3. Send det oppdaterte access-tokenet fra HelseID til Kjernejournal Innlogging-tjenesten. Merk at refresh-tokenet fra HelseID skal EPJ beholde selv.

POST /api/session/refresh
Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...
DPoP: aseqwe231asSD...
X-SOURCE-SYSTEM: EPJ-System, (v1.2.3-RC)
Content-Type: application/json

{
  "sessionId": "<mottatt ved opprettelse av sesjon>"
}

Avslutt Kjernejournal Innlogging-sesjon

Det er to tilfeller hvor Innlogging-sesjonen må avsluttes av EPJ.

• Brukersesjon i EPJ avsluttes av bruker
• Brukersesjon i EPJ timer ut

Når det skjer, så må Kjernejournal Innlogging-sesjonen eksplisitt avsluttes.

1. Request for å avslutte Kjernejournal Innlogging-sesjonen:

POST /api/session/end
Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...
DPoP: aseqwe231asSD...
X-SOURCE-SYSTEM: EPJ-System, (v1.2.3-RC)
Content-Type: application/json

{
  "sessionId": "<mottatt ved opprettelse av sesjon>"
}

Bytte pasient

Når bruker bytter pasient, så må eksisterende sesjon avsluttes hvis den er aktiv. I tillegg må en ny sesjon opprettes for den nye pasienten. Det betyr at EPJ må be om nytt access token fra HelseID og opprette ny sesjon i Kjernejournal Innlogging.

3. Å starte en ny sesjon innebærer å be om nytt access token fra HelseID og opprette en ny Kjernejournal Innlogging-sesjon som beskrevet i seksjonen over