Token-exchange for API-eiere og arkitekter

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.

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

EPJ-applikasjonen er satt opp med en klient i HelseID, som gir tilgang til API 1. EPJ-en ber om en brukerpålogging og tilgang til API 1 gjennom HelseID. HelseID returnerer et Access-token (AT#1) som gir tilgang til API 1.

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

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

API 1 er må derfor be HelseID om et eget Access-token som kan brukes for å gjøre kall til API 2. For å kunne gjøre det, er API 1 satt opp for bruk av Token-exchange i HelseID.

Ettersom API 1 ønsker å gjøre kallet til API 2 på vegne av EPJ-applikasjonen (som en del av den samme kallkjeden), bruker API 1 tokenet AT#1 fra det opprinnelige kallet, og ber HelseID om å veksle dette Access-tokenet inn til et token som kan brukes i kall mot API 2. Dette nye Access-tokenet kalles AT#2 i figuren.

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

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

Hva trengs for å ta i bruk Token-exchange i HelseID?

Dersom vi bruker tjenestene fra eksemepelet over:

• EPJ-applikasjonen: Kaller API 1 som normalt

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

• API 2 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 1 i dette tilfellet). Når API 1 ber om å ta i bruk Token-exchange, må eieren av API 2 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 1 API 2 på vegne av EPJ-applikasjonen). Som API-eier må du ta stilling til om dette er ønskelig.

Det er viktig å være klar over at det bare er API 2 som kan verifisere at et kall er gjort gjennom en Token-exchange-kallkjede. HelseID gjør ingen sjekk på dette i kjøretid. Det ligger altså kun på API 2 å sjekke innholdet i et Access-token.

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 den opprinnelige klienten (EPJ-applikasjonen i eksempelet) og en eventuell pålogget bruker. API 2 vil med andre ord ikke miste opprinnelig kontekst fra HelseID 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 den opprinnelige klienten er blitt godkjent (siden kallet kommer via en annen tjeneste). Vi anbefaler at dette legges inn i avtaleverk for tjenesten sluttbrukeren kaller (API 1 i eksempelet).