Autentisering og tilgang

Open Aidn-API-er krever OAuth 2.0-tilgangstokener som er utstedt for den godkjente integrasjonen. Tilgangen styres av klient- og kommunekonfigurasjonen og av hvilke tilganger klienten har for hvert endepunkt.

OAuth-klientautentisering

De fleste systemintegrasjoner bruker en konfidensiell OAuth-klient med private_key_jwt-autentisering.

Klienten trenger minst ett nøkkelpar. Dette kan håndteres på to måter:

Leverandøren genererer et nøkkelpar og sender bare den offentlige nøkkelen til kommunen eller en Aidn-administrator, som registrerer den i administrasjonsportalen.
Kommunen eller en Aidn-administrator genererer nøkkelparet i administrasjonsportalen og overfører privatnøkkelen sikkert til leverandøren.

Leverandøren lagrer privatnøkkelen sikkert og bruker den til å signere forespørsler om tilgangstoken.

Hvis administrasjonsportalen genererer nøkkelparet, vises privatnøkkelen bare én gang og kan ikke hentes frem senere. Lagre den før dialogen lukkes.

Privatnøkler skal aldri legges i kildekode, skrives til logger eller deles via e-post eller chat.

Klientassertions med private_key_jwt

Med private_key_jwt sender ikke OAuth-klienten en klienthemmelighet. Klienten lager i stedet en kortlivet JWT, en klientassertion, signerer den med den registrerte privatnøkkelen og sender den til OAuth-tokenendepunktet som en del av forespørselen om tilgangstoken.

Tokenforespørselen bør inneholde disse skjemaparameterne:

audience=urn:open.aidn.no
grant_type=client_credentials
client_id=<CLIENT_ID>
scope=<MELLOMROMSSEPARERTE_TILGANGER>
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<SIGNERT_JWT>

Den signerte JWT-en bør identifisere OAuth-klienten og autorisasjonsserveren:

iss: OAuth-klient-ID-en.
sub: OAuth-klient-ID-en.
aud: OAuth-utstederens base-URL for miljøet, ikke tokenendepunktets URL.
iat: tidspunktet assertionen ble utstedt.
exp: kort utløpstid for assertionen.
jti: en unik verdi for denne assertionen.
typ: client-authentication+jwt

JWT-headeren må inneholde signeringsalgoritmen (alg). Hvis en nøkkel-ID (kid) ble oppgitt under klientoppsettet, bør den tas med i JWT-headeren slik at autorisasjonsserveren kan finne den registrerte offentlige nøkkelen som skal brukes til å verifisere assertionen.

Sett aud-claimet til utstederens base-URL i tabellen nedenfor. Ikke bruk /connect/token som audience. Bruk for eksempel https://health.auth.demo.aidn.no for demo, ikke https://health.auth.demo.aidn.no/connect/token. Dette følger den oppdaterte audience-veiledningen i RFC 7523bis, som krever at autorisasjonsserverens issuer identifier brukes som audience for JWT-baserte klientautentiseringsassertions.

URL-er for miljøene

Bruk adressene for miljøet der integrasjonen er aktivert. FHIR-basadressen er utgangspunktet for FHIR-forespørsler. Legg til ressursstier som Patient eller EpisodeOfCare.

Miljø	FHIR-basadresse	OAuth-utstederens base-URL	OAuth-tokenendepunkt
Demo	`https://open.demo.aidn.no/fhir`	`https://health.auth.demo.aidn.no`	`https://health.auth.demo.aidn.no/connect/token`
Produksjon	`https://open.aidn.no/fhir`	`https://health.auth.nhn.aidn.no`	`https://health.auth.nhn.aidn.no/connect/token`

Be om tilgangstokener fra tokenendepunktet ved hjelp av OAuth-klientopplysningene og private_key_jwt-oppsettet for integrasjonen. Bruk bare demo-klientopplysninger i demomiljøet og produksjonsopplysninger i produksjonsmiljøet.

Tilganger

Tilgangene begrenser hva en klient kan gjøre. Klienten kan bare be om tilgangene som er konfigurert for den.

Navnene på tilgangene i Open Aidn er inspirert av SMART on FHIR. Et søk etter EpisodeOfCare krever for eksempel:

Tilgang	Formål
`episodeofcare.search`	Søke etter EpisodeOfCare-ressurser.
`episodeofcare.read`	Lese én EpisodeOfCare-ressurs med ID.

De konkrete tilgangene for en integrasjon avtales under oppstarten og skal samsvare med det godkjente bruksområdet.

Kalle Open Aidn API-er

Hver API-forespørsel må inneholde tilgangstokenet i HTTP-headeren Authorization:

Authorization: Bearer <ACCESS_TOKEN>
Accept: application/fhir+json

Forespørsler og svar bruker FHIR JSON der det er relevant. Søkeendepunkter returnerer en FHIR Bundle der type er satt til searchset.

Etterlevelse og dataminimering

Open Aidn-integrasjoner må følge avtalt formål og datatilgang for kommunen. Som integrasjonspartner skal du:

Bare be om tilgangene som trengs for det godkjente bruksområdet.
Lagre nøkler, klientopplysninger og tilgangstokener sikkert.
Unngå å lagre helsedata med mindre det inngår i det avtalte behandlingsformålet.
Loggfør tilgang på en måte som støtter feilsøking uten å eksponere unødvendige helseopplysninger.
Koordiner nøkkelrotasjon og hendelseshåndtering med kommunen og Aidn.

Aidn håndhever autentisering, autorisasjon, kommunekonfigurasjon og revisjonslogging på plattformsiden. Dette fritar ikke leverandøren fra ansvaret for å beskytte klientopplysninger og håndtere helsedata i tråd med avtalen.

Tilbake til forsiden