01 - System til System - V2

Owned by sven.christiansen
Last updated: Oct 13, 2023
2 min read

 

MERK! Alle nye API-klienter skal benytte V2! (V1 av Token endepunktet for System til System vil ikke støttes etter 31. desember 2023. Alle API-klienter som i dag benytter shared secret MÅ gå over til å benytte RSA-nøkkelpar og V2.

Løsningskomponenter og informasjonsflyt

 

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: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/1552384092

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: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/1368752157

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.