Dette er foreløpig dokumentasjon for bruk av Tillitsrammeverket gjennom HelseID. Mye av teksten som ikke omtaler eksisterende OAuth-protokoller vil kunne endre seg etter hvert.

Hvordan bruker jeg HelseID for overføring av attest?

HelseID skal brukes for mottak av en attest som beskrevet i Tillitsrammeverket, slik at denne kan inkluderes i et Access-token.

Attesten må sendes inn som en JSON-struktur (se under).

Du kan bruke to forskjellige mønstre for å overføre attesten til HelseID:

  • Enten 1) ved å sette attesten i et Request object/Authorization Details (gjennom /authorize-endepunktet) (flyt nummer 1)

  • Eller 2) ved å sette attesten i client_assertion når klienten gjør bruk av Authorization code-parameter og/eller Refresh-token (gjennom /token-endepunktet) (flyt nummer 2)

  • Inkludering av attesten i tokens

    • Hvis attesten er sendt inn ved bruk av flyt nummer 1 (Request Object):
      • Attesten blir inkludert i alle Access-token, så lenge det korresponderende Refresh-tokenet er gyldig
      • For å oppdatere attesten, må klienten gjøre en ny forespørsel mot /Authorize-endepunket
    • Hvis attesten er sendt inn ved bruk av flyt nummer 2 (client_assertion):
      • Attesten inkluderes i Access-token som kommer ut av denne forespørselen; ved en forespørsel mot /token-endepunktet uten attest-informasjon i client_assertion, vil attesten ikke bli satt som et claim i Access-tokenet
      • For å oppdatere attesten, må klienten gjøre en ny forespørsel mot /Token-endepunktet
    • Hvis attesten er sendt inn to ganger (altså ved bruk av både flyt 1 og flyt 2), vil HelseID respondere med en feilmelding (access_denied med beskrivelses-prefikset HID-DOUBLE-STRUCTURE)

Diagrammer for flyt

Flyt nummer 1:

sequenceDiagram Ressurseier (bruker)->>Klient: Ber om pålogging via HelseID Klient->>HelseID: Gjør en forespørsel til /authorize-endepunktet, legger ved et Request-objekt som inneholder attesten HelseID->>HelseID: Validerer attesten, legger den på brukersesjonen HelseID->>Klient: Sender tilbake en respons som inneholder kode Klient->>HelseID: Gjør en forespørsel til /token-endepunktet, ber om scopet for Tillitsrammeverk HelseID->>Klient: Sender tilbake et Access-token som inneholder attesten som et claim Klient->>KJ: Kaller (for eksempel) Kjerneejournal, legger ved Access Token KJ->>KJ: Verifiserer at Access-tokenet er ment for Kjernejournal, henter (f.eks.) ut pasientens journaldokumenter KJ->>Klient: Resultat av API-kall

Flyt nummer 2:

sequenceDiagram Ressurseier (bruker)->>Klient: Ber om pålogging via HelseID Klient->>HelseID: Gjør en forespørsel til /authorize-endepunktet HelseID->>Klient: Sender tilbake en respons som inneholder kode Klient->>HelseID: Gjør en forespørsel til /token-endepunktet, ber om scopet for Tillitsrammeverk og legger ved attesten i client_assertion HelseID->>HelseID: Validerer attesten HelseID->>Klient: Sender tilbake et Access-token som inneholder attesten som et claim Klient->>KJ: Kaller (for eksempel) Kjerneejournal, legger ved Access Token KJ->>KJ: Verifiserer at Access-tokenet er ment for Kjernejournal, henter (f.eks.) ut pasientens journaldokumenter KJ->>Klient: Resultat av API-kall Note over Klient, HelseID: Klienten bruker refresh-token til å oppdatere attesten Klient->>HelseID: Gjør en forespørsel til /token-endepunktet med Refresh-token, ber om scopet for Tillitsrammeverk og legger ved attesten i client_assertion HelseID->>HelseID: Validerer attesten HelseID->>Klient: Sender tilbake et Access-token som inneholder attesten som et claim Klient->>KJ: Kaller (for eksempel) Kjerneejournal, legger ved Access Token KJ->>KJ: Verifiserer at Access-tokenet er ment for Kjernejournal, henter (f.eks.) ut pasientens journaldokumenter KJ->>Klient: Resultat av API-kall

Validering av innholdet i attesten

HelseID validerer innholdet i attesten i flere steg:

  1. Parsing av JSON-innholdet i attesten
  2. Validering av HelseID-klientens tilgang til Tillitsrammeverket
  3. Gjennomgang av strukturen i attestens JSON-innhold
  4. Gjennomgang av innholdet i attesten

Hvis attesten ikke blir validert, vil en av følgende feilkoder bli returnert i error_description-elementet i meldingen fra HelseID:

Prefiks i beskrivelse av feilmelding Feilmeldingskontekst
HID-JSON JSON-struktuen i attesten kunne ikke parses, eller var for lang
HID-TYPE JSON-struktuen inneholdt ingen gjenkjennbar type
HID-AUTH HelseID-klienten har manglende autorisasjon for forespørselen
HID-STRUCTURE Feil JSON-struktur i attesten; uønskede eller manglende JSON-noder ble observert
HID-CONTENT Feil innhold i attesten; feil system og/eller innholdet matcher ikke systemet
HID-GRANT Klienten har bruk en feil grant-type (flyt) i kallet til HelseID
HID-DOUBLE-STRUCTURE Klienten har sendt inn attest-struktur både som Request Object og som element i client_assertion

Eksempel på en (URL-kodet) feilmelding fra HelseID:

{
      "error":"invalid_request",
      "error_description":"HID-CONTENT: The JSON content could not be validated.\nAt node \u0027$.practitioner_role.organization.identifier.value\u0027: The child organization sent in the request is not present in the child organization whitelist for the client with client_id = \u0027helseid-sample-client-credentials-with-underenhet\u0027. Please check that this organization number has been set for the client in HelseID Selvbetjening."
},

Utvidelse av innholdet i attesten

Etter at en attest har blitt validert, beriker HelseID innholdet i attesten. Dette fører til at Access-tokenet får et innhold som korresponderer med informasjonsmodellen i Tillitsrammeverket. Det nye innholdet inkluderer blant annet informasjon om bruker (fødselsnummer og hpr-nummer) og navn på kodeverk og verdi for hvert informasjonselement.

Pasientinformasjon

Foreløig vil ikke HelseID kunne overføre pasientinformasjon i attesten. Det arbeides med å finne en løsning for dette.

DPoP

Tillitsrammeverket krever at klienten som har fått utlevert en attest gjennom HelseID, også bruker DPoP / Demonstrating Proof of Possession for å sikre at tokenet ikke lett kan bli stjålet. Se mer om dette her.

PAR

Dette er et fremtidig krav. HelseID vil implementere funksjonalitet for det i 2024.

Tillitssrammverket krever at før en klient ber om å få utlevert en attest gjennom HelseID, skal den bruke mekanismen PAR / Pushed Authorization Requests. Denne mekanismen er satt opp for å sikre integritet og konfidensialitet for informasjonsinnholdet som sendes fra klienten til HelseID.

Overføring av attest via Authorization Details i et Request Object (flyt 1)

HelseID har støtte for RFC 9396 - Rich Authorization Requests og en klient kan overføre attesten som en verdi med å bruke denne mekanismen. Type skal da settes til nhn:tillitsrammeverk:parameters, og hele attesten inkludert type inkluderes som et element i authorization_details-arrayet. Et eksempel på et request object med en komplett authorization_details struktur er vist under:

{
  "aud": "https://helseid-sts.test.nhn.no",
  "iss": "client id her",
  ...
  "authorization_details": [{
     "type": "nhn:tillitsrammeverk:parameters",
     "practitioner": {
       "authorization": {
         "code": "AA",
         "system": "urn:oid:2.16.578.1.12.4.1.1.9060"
       },
       "legal_entity": {
         "id": "946469045",
         "system": "urn:oid:2.16.578.1.12.4.1.4.101"
       },
       "point_of_care": {
         "id": "983658776",
         "system": "urn:oid:2.16.578.1.12.4.1.4.101"
       },
       "department": {
         "id": "4206043",
         "system": "urn:oid:2.16.578.1.12.4.1.4.102"
       }
     },
     "care_relationship": {
       "healthcare_service": {
         "code": "S03",
         "system": "urn:oid:2.16.578.1.12.4.1.1.8655"
       },
       "purpose_of_use": {
         "code": "TREAT",
         "system": "urn:oid:2.16.840.1.113883.1.11.20448"
       },
       "purpose_of_use_details": {
         "code": "15",
         "system": "urn:oid:2.16.578.1.12.4.1.1.9151"
       },
       "decision_ref": {
         "id": "30F4AB40-DBC2-41A7-8AC4-181AD3FDC25B",
         "user_selected": true
       }
     },
     "patients": [{
       "point_of_care": {
         "id": "983658776",
         "system": "urn:oid:2.16.578.1.12.4.1.4.101"
       },
       "department": {
         "id": "4206043",
         "system": "urn:oid:2.16.578.1.12.4.1.4.102"
       }
     }] 
   }]
}

Overføring av attest via Client Assertion (flyt 2)

Før utlevering av tokens må alle HelseID-klienter autentisere seg med bruk av en Client Assertion RFC 7523. Dette er en mekanisme der klienten signerer en JWT med sin privatnøkkel, HelseID kan da autentisere klienten ved å verifisere signaturen med en offentlig nøkkel som er knyttet til klienten.

I tillegg til standardinnholdet i en Client Assertions støtter HelseID at klienten legger ved utvidet informasjon på samme måte som når man bruker Authorization Details. Informasjonen struktureres på akkurat samme måte, men i stedet for å bruke navnet authorization_details bruker man navnet assertion_details.

Et eksenmpel på en client assertion med en assertion_details-struktur er vist under:

{
  ...
  "assertion_details": [{
     ... som over ...
   }]
}