Bruk av HelseID og accesstoken i SFM Full

HelseID benyttes av SFM datadeling API direkte og SFM klient indirekte via Session.

Se ellers felles informasjon i "Common"

Tokenet skal ha et claim som er spesifikt for SFM (SFM-id), og kun ha SFM som audience. Det er to scopes som er relevant i SFM full:

  • SFM portaler og integrasjoner: Scope: e-helse:sfm.api/sfm.api, Beskrivelse: Benyttes for SFM Portaler, SFM Datadeling API og SFM Basis API.
  • SFM migrering: Scope: e-helse:sfm.api/sfm-migrering.api , Beskrivelse: Benyttes for første gangs opplasting av pasient- og virksomhetsdata fra EPJ system til SFM.

Ved å be om et accesstoken kan et system dermed benytte seg av et API, og dersom sikringsmekanismene ellers er gode kan API-tilbyder stole på innholdet. Fordi systemet gir fra seg tokenet (til den som tilbyr API) er det tokenet som definerer hvilket API/ressurs det er ment å gi tilgang til. Accesstoken har relativt kort levetid.

Klienten kan også be om et refreshtoken som har lengre levetid, og kan benytte dette til å fornye aksesstoken så lenge refreshtokenet lever. Refresh-token er ikke ment å forlate klientapplikasjonen og kan derfor ha lengre levetid.

SFM er bygget på en slik måte at API kall som kommer inn, eller funksjoner som gjøres i SFM klient medfører innmelding av opplysninger eller oppslag i sentrale systemer som skal gjøres på vegne av klienten/brukeren som benytter SFM. SFM er derfor konfigurert i HelseID til å kunne utføre en "token exchange", altså å bytte ut et token med audience for SFM, til et token som gir tilgang til f.eks. Reseptformidleren. Tokenet vil da inneholde opplysninger om opprinnelig klient, om SFM som har byttet token og audience for å gi tilgang til Reseptformidlerens API.

Det er noen viktige ting å være klar over:

  • På grunn av mulig klokke-forskyvning anbefaler HelseID at klientapplikasjonen benytter verdien ExpiresIn (seconds) som returneres sammen med tokenet fra HelseId for å støtte refresh-algoritme internt.
  • SFM fullversjon med GUI klient må opprette en sesjon mot SFM med endepunktet: /api/Session/create
  • SFM fullversjon med GUI klient må oppfriskes med nytt token når EPJ har gjort refresh. Dette gjøres i API Datadeling med endepunktet: /api/Session/refresh
  • På samme måte skal sesjonen lukkes dersom brukeren logger av EPJ systemet: /api/Session/end.

SFM har en sesjon for hver bruker i en virksomhet. Dette er slik for å unngå at det skal hope seg opp med sesjoner når bruker hopper mellom maskiner. Sesjon er her en knytting mellom accesstoken og cookie. En bruker kan ta create session fra mange maskiner og det fungerer for bruker i alle browsere fram til han på en av maskinene velger å logge ut. Da er det krav om å avslutte sesjon og EPJ sender avslutt sesjon. Når bruker kommer til en av de andre maskinene som bruker sesjonen, så finnes ikke cookie og kall fra SFM feiler. EPJ må da ta en ny create session og starte browser igjen for at bruker skal kunne fortsette å jobbe på pasienten.

Single tenant klient

For single tenant klienter i HelseID er både orgnr_parent og SFM-id prekonfigurert. Det er kun dersom det er behov for angivelse av underenhet at det må legges til informasjon i request objektet.

Multi tenant klient

En multi tenant klient må alltide legge med detaljer om orgnaisasjonen til kunden. Dette kommer gjennom delegering fra Altinn, og i test kan det legges til "tenats" fritt i selvbetjening. Den generelle tilnærmingen er at en kunde/tenenat har sitt eget journalsystem, og det vil da gjerne være 1-1 forhold mellom kunde, organisasjonsnummer og journa-id.

Det finnes tilfeller hvor flere organisasjoner har felles journal etter det som heter §9 samarbeid. Da kan journalleverandører velge om det skal benyttes en felles journal-id eller ha separate for hver enkelt kunde. For SFM er det da vesentlig at dersom ny kunde (Organization) skal ha egen jounal-id må den inkluderes i instansen med et token som er kjent. Med andre ord: kunde nr to må skrives til SFM med sin nye Organization.Identifier.SFM-id med et token som har kjent journal-id (eksisterende kunde)

Under er et eksmepel på deler av token request for multi tentant. Se HelseID sine sider for detaljer.

"authorization_details": [
    {
      "type": "helseid_authorization",
      "practitioner_role": {
        "organization": {
          "identifier": {
            "system": "urn:oid:1.0.6523",
            "type": "ENH",
            "value": "NO:ORGNR:100100126:999944582"
          }
        }    
      }
    },
    {
      "type": "nhn:sfm:journal-id",
      "value": {
        "journal_id": "7fbfbcbd-6f08-4e95-9f7a-9d69c40f6a35"
      }
    }
 ]

I eksempelet over er det angitt hvilke to organisasjonsnummer (toppnivå/parent og virksomhet/child) som skal angis i token, samt at journal-id angis for korrekt instans av SFM. Det kan være flere journal-id som peker på samme instans, f.eks. en pr juridisk enhet. Det er EPJ systemet sitt ansvar å ikke samle data om pasienter for flere virksomheter når det ikke foreligger juridiske avtaler om journalsamarbeid.

Merk: der er detalj i JSON strukturen her: JSON variabelen “journal_id” har understrek, mens helseID scope har bindestrek. Dette er av tekniske grunner.

For mer informasjon om HelseID: https://www.nhn.no/helseid/hvordan-ta-i-bruk-helseid/

Informasjon om journal-id: HelseID info om journal-id/sfm-id

For utviklere: How do I, as a developer, get started with HelseID

For mer informasjon om JWT token: https://jwt.io/