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.

Innsending av attest

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-endepunktet
  • 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:

Flyt nummer 2:

Hva sender klienten inn, og hva valideres?

• Klienten sender inn en nedskalert versjon av attesten: for at HelseID ikke skal trenge å validere navn på kodeverk og assigner/authority for kodeverk, så skal ikke klienten sende inn disse parametrene; HelseID utvider i stedet attesten med disse parametrene.
• Dette innebærer også at klienten ikke skal sende inn:
  • helsepersonellets fødselsnummer og navn (practitioner:identifier)
  • helsepersonellets HPR-nummer (practitioner:hpr-nr)
• Klienten skal foreløpig heller ikke sende inn pasientinformasjon i attesten (patients:identifier). Denne informasjonen må klienten sende inn i innholdet i et POST-kall til API-et som skal konsumeres. Det arbeides med å finne en løsning som skal gjøre det mulig å kunne sende inn pasientinformasjon gjennom attesten.
• Kategorien patients må struktureres som et JSON-array, men som følge av at det ikke går an å sende inn pasientinformasjon, vil det foreløpig bare kunne sendes inn ett opbjekt i dette arrayet.

Obligatoriske elementer i attesten

Ikke alle elementene i attesten er obligatoriske, men klienten må sende inn følgende felter i attesten:

Ikke-obligatoriske elementer i attesten

Eksempel på en minimal struktur i JSON-format (kun obligatoriske felter):

{
    "type": "nhn:tillitsrammeverk:parameters",
    "practitioner": {
        "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"
        }
    },
    "care_relationship": {
        "healthcare_service": {
            "code": "S03",
            "system": "urn:oid:2.16.578.1.12.4.1.1.8655"
        },
        "decision_ref": {
            "id": "30F4AB40-DBC2-41A7-8AC4-181AD3FDC25B",
            "user_selected": true
        }
    },
    "patients": [{}]
}

Eksempel på en komplett struktur i JSON-format:

{
    "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"
            }
        }
    ]
}

Validering av innholdet i attesten

HelseID validerer innholdet i attesten i flere steg:

1. HelseId sjekker at klienten har en godkjent tilgang til Tillitsrammeverket
2. HelseId parser JSON-strukturen i attesten og validerer at det er en godkjent JSON-struktur
3. HelseId gjør en gjennomgang av strukturen i attestens JSON-innhold og sjekker at strukturen matcher modellen for Tillitsrammeverket
4. HelseId gjør en gjennomgang av innholdet i attesten og sjekker at innholdet i feltene er i korrespondanse med modellen for Tillitsrammeverket

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

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, vil HelseID berike 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.

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.

PAR

Tillitsrammverket 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": {
       ...
     },
     "care_relationship": {
       ...
     },
     "patients": [{
       ...
     }] 
   }]
}

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 ...
   }]
}