Koble en konsument (EPJ) til MyHealth-portalen

Dette dokumentet beskriver hvordan et fagsystem/EPJ kobler seg til MyHealth-portalen. Dokumentet forklarer autentisering, krav til HelseID-klient og hvordan EPJ etablerer en sesjon i portalen.

Kort oppsummert

• Autentiseringen av helsepersonell skjer i EPJ mot HelseID (ikke i portalen).

• EPJ henter et gyldig DPoP-access token fra HelseID og bruker det for å opprette sesjon i MyHealth.

• For å knytte EPJ-sesjon og nettleser-sesjon brukes PKCE (code_challenge / code_verifier).

• EPJ åpner portalen i nettleser med engangskoden (code) fra MyHealth.

1. Forutsetninger

EPJ må ha en registrert HelseID-klient (client_id) som støtter: Les mer om helseId

• DPoP

• PKCE (public client)

Tokenet som sendes til MyHealth må oppfylle følgende krav:

EPJ må også kunne:

• Generere og signere DPoP-bevis

• Generere PKCE code_verifier og code_challenge (S256)

• Sette nødvendige claims ved opprettelse av sesjon

2. Flyt (høynivå)

1. Helsepersonell logger inn i EPJ.

2. EPJ gjennomfører autorisasjonsflyten mot HelseID og henter et DPoP-access token.

3. EPJ kaller POST /api/session/create i MyHealth med token, DPoP-bevis, PKCE challenge og claims.

4. MyHealth returnerer sessionId og en engangskode (code).

5a. EPJ serverer en nettside med automatisk POST til MyHealth (anbefalt):

eller

5b. EPJ åpner nettleser på:

-/start-session?code=<code>&ehr-code-verifier=<code_verifier>

Sekvensdiagram (Anbefalt POST-redirect-flyt)

sequenceDiagram
  actor Helsepersonell
  participant EPJ
  participant HelseID
  participant MyHealth

  rect gray
    Note over EPJ: Autentisering i EPJ
    Helsepersonell ->> EPJ: Klikk «Logg inn»
    EPJ ->> HelseID: Autorisasjonsflyt (DPoP)
    HelseID -->> EPJ: DPoP access token
    EPJ ->> HelseID: GET /connect/userinfo
    HelseID -->> EPJ: Userinfo
  end

  EPJ ->> EPJ: Generer PKCE (code_verifier + code_challenge)

  EPJ ->> MyHealth: POST /api/session/create
  Note right of EPJ: Headers: Authorization: DPoP <token>, DPoP: <proof>. Body: ehrCodeChallenge + claims (authorization, healthCareFacilityType).

  MyHealth -->> EPJ: { sessionId, code }

  EPJ ->> EPJ: Serverer side med auto-POST-skjema
  EPJ ->> Helsepersonell: Åpner nettleser med side
  Helsepersonell ->> MyHealth: POST /api/session/start<br/>code=...&ehr-code-verifier=...
  MyHealth ->> MyHealth: Valider PKCE og opprett sesjon
  MyHealth -->> Helsepersonell: 303 See Other + Set-Cookie
  Helsepersonell ->> MyHealth: GET /myhealth-portal/search_patient
  MyHealth -->> Helsepersonell: Portal UI

Sekvensdiagram (Gammel GET redirect-flyt)

sequenceDiagram
  actor Helsepersonell
  participant EPJ
  participant HelseID
  participant MyHealth

  rect gray
    Note over EPJ: Autentisering i EPJ
    Helsepersonell ->> EPJ: Klikk «Logg inn»
    EPJ ->> HelseID: Autorisasjonsflyt (DPoP)
    HelseID -->> EPJ: DPoP access token
    EPJ ->> HelseID: GET /connect/userinfo
    HelseID -->> EPJ: Userinfo
  end

  EPJ ->> EPJ: Generer PKCE (code_verifier + code_challenge)

  EPJ ->> MyHealth: POST /api/session/create
  Note right of EPJ: Headers: Authorization: DPoP <token>, DPoP: <proof>. Body: ehrCodeChallenge + claims (authorization, healthCareFacilityType).

  MyHealth -->> EPJ: { sessionId, code }

  EPJ ->> Helsepersonell: Åpner nettleser med URL
  Helsepersonell ->> MyHealth: GET /start-session?code=...&ehr-code-verifier=...

  MyHealth ->> MyHealth: Valider PKCE og opprett sesjon
  Helsepersonell -->> MyHealth: Redirect til /myhealth-portal/search_patient (GET)
  MyHealth -->> Helsepersonell: Portal UI

3. Endepunkt for å opprette sesjon

Body (eksempel)

{
  "ehrCodeChallenge": "<base64url(SHA256(code_verifier))>",
  "claims": {
    "authorization": {
      "code": "LE",
      "system": "urn:oid:2.16.578.1.12.4.1.1.9060",
      "assigner": "https://www.helsedirektoratet.no/"
    },
    "healthCareFacilityType": {
      "code": "KA02",
      "system": "urn:oid:2.16.578.1.12.4.1.1.8663"
    }
  }
}

svar 
{
  "sessionId": "<uuid>",
  "code": "<engangskode>"
}

4. Starte portalen i nettleser

For å opprette en godkjent sesjon i nettleseren må EPJ kalle et av start-endepunktene i MyHealth.

POST /api/session/start (Anbefalt)

POST /api/session/start
Content-Type: application/x-www-form-urlencoded

code=<engangskode>&ehr-code-verifier=<code_verifier>

Svar: 303 See Other

Hvorfor bruke POST? Den største fordelen med å bruke POST er at aktiveringskodene (code og ehr-code-verifier) ikke blir en del av URL-en. Det betyr at sensitiv informasjon verken blir synlig i nettleserens adressefelt eller lagret i nettleserhistorikken.

Tips for implementering: Siden nettlesere vanligvis navigerer til et annet nettsted med GET, kan det kreve litt ekstra logikk for å trigge en POST-request mot MyHealth direkte fra EPJ. To vanlige løsninger er:

1. Usynlig skjema: EPJ serverer en side med et skjema som inneholder parametrene, som submittes automatisk med JavaScript etter innlogging.
2. OAuth 2.0 Form Post: Backend-serveren kan generere en nettside som automatisk poster til MyHealth, slik som beskrevet i spesifikasjonen OAuth 2.0 Form Post Response Mode.

GET /api/session/start

GET /api/session/start?code=<engangskode>&ehr-code-verifier=<code_verifier>

Svar: 200 OK

Merk: GET returnerer kun 200 OK og setter cookies. Sikkerhetsadvarsel: Ved GET vil parametrene være synlige i nettleserens adressefelt og lagres i nettleserhistorikken.

5. Krav til claims

  "code": "LE",
  "system": "urn:oid:2.16.578.1.12.4.1.1.9060",
  "assigner": "https://www.helsedirektoratet.no/"
}

Godkjente roller LE, SP

healthCareFacilityType

{
  "code": "KA02",
  "system": "urn:oid:2.16.578.1.12.4.1.1.8663"
}

6. Eksempel med cURL

curl -X POST \
  "https://<myhealth-host>/api/session/create" \
  -H "Authorization: DPoP <HelseID_access_token>" \
  -H "DPoP: <dpop-proof-jws>" \
  -H "X-SOURCE-SYSTEM: EPJ-System (v1.2.3)" \
  -H "Content-Type: application/json" \
  -d '{
    "ehrCodeChallenge": "<challenge>",
    "claims": {
      "authorization": {
        "code": "LE",
        "system": "urn:oid:2.16.578.1.12.4.1.1.9060",
        "assigner": "https://www.helsedirektoratet.no/"
      },
      "healthCareFacilityType": {
        "code": "KA02",
        "system": "urn:oid:2.16.578.1.12.4.1.1.8663"
      }
    }
  }'