Autentiseringsflyt

Før EPJ kan opprette en sesjon i Kjernejournal Single Sign On må den ha en aktiv sesjon med DPoP, se HelseID sin dokumentasjon på bruk av DPoP. Alle backend kall mot Kjernejournal Single Sign On krever autentisering med DPoP.

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

• Opprettelse av sesjon
• Vedlikeholde 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.

Opprettelse av Kjernejournal SSO-sesjon

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

• Hente access tokens fra HelseID
• Opprett Kjernejournal SSO-sesjon ved å sende access token til Kjernejournal SSO
  • 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 SSO-sesjon
  • SSO-sesjonen krever et HelseID access-token, en pasient-id og et samtykkegrunnlag (access_basis)
  • SSO-sesjonen brukes for åpne en websesjon mot Kjernejournal Portal

Pasient identifikator

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

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
3. Generer par av ehr_code_challenge, ehr_code_verifier
   • For å koble SSO-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 SSO-sesjon Før man kan åpne Kjernejournal Portal, så må man opprette en sesjon i Kjernejournal SSO.

Dette er et eksempel på en request.

• Authorization
  • HelseID DPoP Access token fra steg 2
• DPoP
  • DPoP-signatur, se HelseID
• patient_identifier
  • Pasientens fødselsnummer eller D-nummer
• access_basis
  • Dette er samtykkegrunnlag, og må være en av følgende verdier: AKUTT, SAMTYKKE, UNNTAK
• X-SOURCE-SYSTEM
  • Påkrevd header
  • Fritektsfelt for å identifiere kildesystemet i logger

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

{
  "ehr_code_challenge": <Verdien av challenge generert i steg 3>,
  "claims": {
    "patient_identifier": {
      "id": "id-streng",
      "system": "id-system",
      "authority": "autoritativ kilde"
    },
    "access_basis": "AKUTT" eller "SAMTYKKE" eller "UNNTAK"
  }
}

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 SSO-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 SSO-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 SSO-sesjon

Før HelseID-access tokenet utløper, så må EPJ hente nytt token fra HelseID og sende det til Kjernejournal SSO-tjenesten.

3. Send det oppdaterte Access Tokenet fra HelseID til Kjernejournal SSO-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-X v1.2.3
Content-Type: application/json

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

Avslutt Kjernejournal SSO-sesjon

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

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

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

1. Request for å avslutte Kjernejournal SSO-sesjonen:

POST /api/session/end
Authorization: DPoP eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...
DPoP: aseqwe231asSD...
X-SOURCE-SYSTEM: EPJ-System-X v1.2.3
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 SSO.

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