Token Exchange for API-eiere

Token Exchange er en utvidelse til OAuth 2.0, en av protokollene som HelseID bygger på. Token Exchange brukes når en tjeneste har behov for å kalle andre tjenester på vegne av en autentisert bruker eller virksomhet. Formålet med dette dokumentet er å gi API-eiere et grunnlag for å vurdere om de ønsker å åpne for bruk av Token Exchange mot sine tjenester.

Hvordan fungerer flyten i Token Exchange?

Open

Figuren ovenfor gir en enkel fremstilling av Token Exchange-flyten.

I eksempelet har vi et EPJ-system (EPJ) som opptrer på vegne av en juridisk enhet (kommune, legekontor el.l.). Dette EPJ-systemet ønsker å hente data fra et API (API A). Dette API-et er beskyttet med HelseID, og krever dermed et gyldig Access Token for å utlevere data.

EPJ-systemet er satt opp med en klient i HelseID, som gir tilgang til API A. EPJ-en bruker klientinformasjonen sin for å be om en brukerpålogging og tilgang til API A gjennom HelseID. HelseID returnerer et Access Token (AT#1) som gir tilgang til API A.

EPJ-systemet gjør et kall til API A ved å benytte AT#1. API A inspiserer innholdet i tokenet og ser at det oppfyller kravene for å få tilgang. API A ser også at kallet kommer fra EPJ.

For å fullføre forespørselen fra EPJ trenger API A data fra API B. Ettersom API B også er beskyttet med HelseID må API A bruke et Access Token for å gjøre dette kallet. AT#1 som allerede har blitt brukt av EPJ i kallet mot API A gir kun tilgang til API A, og kan ikke brukes til å kalle API B.

API A er dermed nødt til å be om et eget Access Token som kan brukes for å gjøre kall til API B. For å kunne gjøre det, må API A settes opp med Token Exchange i HelseID.

Når API A er satt med Token Echange i HelseID, blir det satt opp både som et API og som en Token Exchange-klient. For å be om et token som kan brukes ved kall til API B må API A bruke klientkonfigurasjonen sin. Ettersom API A ønsker å gjøre kallet til API B på vegne av EPJ (som en del av den samme kallkjeden), bruker API A AT#1 fra det opprinnelige kallet. API A ber HelseID om å veksle dette Access Tokenet inn til et token som kan brukes i kall mot API B. Dette nye Access Tokenet blir i figuren AT#2.

API A bruker AT#2 for å gjøre kallet til API B. API B inspiserer AT#2 og ser at dette tokenet er et resultat av Token Exchange. Dataene i AT#2 viser at EPJ har gjort det opprinnelige kallet til API A, og at API A har vekslet inn det opprinnelige tokenet for å kalle API B.

API B har dermed all informasjonen det trenger om den juridiske enheten som startet det opprinnelige kallet, og hvem som har gjort Token Exchange.

Hva må gjøres for å ta i bruk Token Exchange i HelseID?

Dersom vi bruker tjenestene fra eksemepelet over:

• EPJ: Kaller API A som normalt

• API A: Må konfigureres i HelseID Selvbetjening til å bruke Token Exchange, samt be om tilgang til API-er det vil kalle (API B i vårt tilfelle). Etter at API B har godkjent denne tilgangen, får API A en egen klientkonfigurasjon som det må bruke til Token Exchange.

• API B: Må konfigureres i HelseID Selvbetjening slik at det skal kunne velges i klientkonfigurasjoner som bruker Token Exchange. Det vil da bli tilgjengelig å velge for APIer som bruker Token Exchange (API A i dette tilfellet). Når API A ber om å ta i bruk Token Exchange, må eieren av API B godkjenne dette.

Token Exchange er en delegeringsmekanisme

Ved å tillate bruk av Token Exchange mot en tjeneste, åpner man opp for at andre tjenester kan kalle denne tjenesten på vegne av noen andre (i eksempelet kaller API A API B på vegne av EPJ). Som API-eier må du ta stilling til om dette er ønskelig.

I tokenet som brukes i forespørselen til tjenesten kan man se at det er blitt gjort en Token Exchange og hvilken tjeneste som har utført denne. I tillegg ligger informasjon om opprinnelig klient (EPJ i eksempelet) og en eventuell pålogget bruker. API B vil med andre ord ikke miste opprinnelig kontekst dersom det har åpnet for Token Exchange.

Noen tjenester krever at det signeres egne avtaler før de kan utlevere data. Dette blir mer utfordrende ved Token Exchange, da man åpner for at det gjøres kall mot tjenesten uten at opprinnelig klient er blitt godkjent (siden kallet kommer via en annen tjeneste). Vi anbefaler at dette legges inn i avtaleverk for tjenesten sluttbrukeren kaller (API A i eksempelet).