01 - System til System

Owned by sven.christiansen
Last updated: Jun 03, 2024
3 min read

Innledning

Tidligere måtte API-klienter, i system-til-system kontekst, autentisere seg mot Helsenorge sin egen Oauth2 tjeneste (Helsenorge STS). Videre var det dennes /Token endepunkt som måtte kontaktes for å få AksessToken som gir tilgang til API’ene på Helsenorge.

Det er nå implementert en løsning på Helsenorge der det aksepteres AksessToken fra HelseId for tilgang til API’ene på Helsenorge. Dette betyr at API-klienter kan benytte HelseId sin selvbetjeningsløsningen for å be om tilgang til de Helsenorge API’er som operere i maskin-til-maskin kontekst. I HelseId er alle metoder i Helsenorge external-API definert med hvert sitt scope.

image-20240429-075003.png

MERK! Det vil forløpende tilgjengeliggjøres flere av API-funksjonene på Helsenorge på denne måten. Om API-funksjonen er tilgjengelig via HelseId eller ikke, vil framgå i dokumentasjonen på dette nettstedet av den enkelte API-funksjon.

 

Løsningskomponenter og informasjonsflyt ved bruk av Helsenorge sin STS

 

 

Sekvensen er som følger:

  • Når systemet trenger å benytte et API på Helsenorge eller i PVK, gjør systemet et kall mot Helsenorge Sikkerhetstjeneste.

  • Helsenorge Sikkerhetstjeneste autentiserer systemet/klienten.

  • Helsenorge Sikkerhetstjeneste sjekker hvilke autorisasjoner det aktuelle system/klient har og gir ut et AcsessToken som representerer disse rettighetene.

  • Systemet kaller et Helsenorge API-endepunkt og ber om tilgang til ressurs, AcsessToken er med i requesten

  • Helsenorge API-tjeneste kontrollerer at de rettigheter som trengs er representert av AcsessTokenet.

  • API-kall utføres og resultat returneres til systemet.

Teknologi og forutsetninger

  • Helsenorge sikkerhetstjeneste er eksponert i et endepunkt der den representerer en STS - Secure Token Service

  • Det eksterne systemet autentiserer seg ved å benytte såkalt "Client Credentials Grant" slik dette er spesifisert i Kapittel 4.4 i Oauth2 spesifikasjonen

  • Det kreves at klienten er "Confidential client", dvs. at den kan beskytte en hemmelighet

Hvordan benytte Helsenorge Sikkerhetstjeneste

URL’er til Helsenorge sikkerhetstjeneste

Hvert miljø har sin egen STS og tokenet som returneres fra denne gir kun tilgang til API kall mot samme miljø.

https://[BaseURL]/sts/v2/token

Base URL til endepunktene i de forskjellige miljøene finner du her: Testmiljøer og endepunkter

Kall til Helsenorge sikkerhetstjeneste

  • HTTP verb: POST

  • Body (med tilhørende angivelse i header) skal være: application/x-www-form-urlencoded

Request

Headers

Key

Value

Key

Value

Content-Type

application/x-www-form-urlencoded (Ikke implementert enda, men kommer: application/json)

Parametere

Key

Type

Påkrevd

Value

Kommentar

Key

Type

Påkrevd

Value

Kommentar

client_id

string

Ja

En GUID som identifiserer klienten

Utstedes av NHN. (Api Client ID)

grant_type

string

Ja

client_credentials

 

client_assertion_type

string

Ja

Skal ha verdien "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

Skal ha verdien "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"

client_assertion

string

Ja

JSON Web Token (JWT) generert av API-klient og signert med API-klientens private nøkkel.

Se: Client Assertion

Den offentlige nøkkelen (i nøkkelparet) registreres på forhånd i Helsenorge sikkerhetstjeneste.

Response

Vellykket response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Content-Type: application/json

Parameter

Type

Verdi

Kommentar

Parameter

Type

Verdi

Kommentar

access_token

string

Generert referanse JWT

Er av type JWT med claims for klient id og referanse token.

Benyttes videre for kall til andre API'er til Helsenorge.

expires_in

int (antall sekunder)

Default: 30 minutter i sekunder

Andre verdier kan defineres dersom det foreligger grunner for dette.

token_type

string

bearer



scope

string

liste av scopes (separert med mellomrom) som API-klienten har tilgang til. (For framtidig bruk).

 

Response - Feilet

Plassering

Navn

Verdi

Plassering

Navn

Verdi

Body

error

 

 

error_description

 

Mulige feilkoder

HTTP statuskode

Feilkode

Beskrivelse

HTTP statuskode

Feilkode

Beskrivelse

400

invalid_request

The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than
once, or is otherwise malformed.

400

unauthorized_client

The client is not authorized to request an authorization
code using this method.

400

access_denied

The resource owner or authorization server denied the
request.

400

unsupported_response_type

The authorization server does not support obtaining an
authorization code using this method.

400

invalid_scope

The requested scope is invalid, unknown, or malformed.

400

server_error

The authorization server encountered an unexpected
condition that prevented it from fulfilling the request.
(This error code is needed because a 500 Internal Server
Error HTTP status code cannot be returned to the client
via an HTTP redirect.)

503

 

The authorization server is currently unable to handle
the request due to a temporary overloading or maintenance
of the server.