Interfaces GBC Server

GBC Server Interface

getMetadataGBC

Feature informatie

Inhoud en formaat van een metadataRequest

De metadata van de GBC Server kan, conform RFC 8414, worden opgehaald op een well-known URL die kan worden geconstrueerd m.b.v. een identifying-URL die de GBC Server (zie section-3.1 van RFC8414) hanteert om zichzelf als issuer te identificeren.

Dit betekent dat bij een identifying-URL die gelijk is aan: https://FQDN/path-extension, de metadata kan worden verkregen bij: https://FQDN/.well-known/oauth-authorization-server/path-extension.

De identifying-URL dient uniek te zijn voor de zorgaanbieder voor wie de GBC Server haar diensten aanbiedt. De GBC Server kan dit doen middels unieke path-extensions, bijvoorbeeld door hier de URA van de zorgaanbieder in op te nemen.

De metadata die wordt geretourneerd geeft een client informatie over hoe gegevens kunnen worden uitgewisseld met een specifieke zorgaanbieder.

Voorbeeld:

• identifying-URL: https://gbc.deveste.nl/ura/12345678 (of DID is gelijk aan did:web:gbc.deveste.nl:ura:12345678), dan is

• well-known URL: https://gbc.deveste.nl/.well-known/oauth-authorization-server/ura/12345678

Een metadataRequest wordt verzonden middels een HTTP GET operation.

Inhoud en formaat van een metadataResponse

De metadataReponse omvat tenminste de volgende attributen:

• issuer (de identifying-URL van de GBC Server);

• token_endpoint;

• token_endpoint_auth_methods_supported;

• token_endpoint_auth_signing_alg_values_supported;

• response_types_supported;

• grant_types_supported.

RFC 8414 staat uitbreiding van de metadataResponse met extra attributen toe. Clients die een attribuut niet kennen moeten het negeren.

De GBC Server moet de volgende authenticatie methoden ondersteunen:

• private_key_jwt.

De GBC Server dient de volgende signing algoritmen te ondersteunen:

• ES256 (Elliptic Curve P-256 o.b.v. SHA-256) - aanbevolen;

• ES512 (Elliptic Curve P-521 o.b.v. SHA-512).

De GBC Server dient de volgende grant-types te ondersteunen:

• urn:ietf:params:oauth:grant-type:jwt-bearer.

Indien de GBC Server slechts grant-type urn:ietf:params:oauth:grant-type:jwt-bearer ondersteunt, dan dient het attribuut response_types_supported gevuld te worden met:

• none.

Voorbeeld:

{
  "issuer": "https://gbc.deveste.nl/ura/12345678",
  "token_endpoint": "https://gbc.deveste.nl/token/ura/12345678",
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "ES256",
    "ES512"
  ],
  "response_types_supported": [
    "none"
  ],
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:jwt-bearer"
  ]
}

De response die wordt geretourneerd bevat daarnaast de volgende headers:

Cache-Control: must-revalidate, max-age=<max-age-metadata>
Pragma: no-cache

Een client mag verkregen metadata conform de Cache-Control header directives, zoals beschreven in RFC 7234, cachen.

De waarde van max-age-metadata is configureerbaar in de GBC Server. Initiële waarde is 14400 seconden (4 uur).

HTTP statuscodes

Zoals gebruikelijk voor HTTP GET requests. Zie ook: RFC 9110.

getTokenGBC

Inhoud en formaat van een tokenRequest

Deze interface is gebaseerd op het Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants, en specifiek hierbinnen op het JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.

Een tokenRequest wordt middels een HTTP POST verzonden naar het token endpoint dat is verkregen uit getMetadataGBC en bevat de volgende attributen:

Voorbeeld:

POST /ura/12345678 HTTP/1.1
Host: gbc.deveste.nl 
Content-Type: application/x-www-form-urlencoded 

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer 
&assertion=eyJhbGciOiJFUzI1NiIskjsadfieko9
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer 
&client_assertion=eyJhbGciOiJFUzI1NiIsioweqicmsje
&scope=gbc.contextcode.MEDICATIE%3Amedicatie%20patient%2FMedicationRequest.rs%20patient%2FMedicationDispense.s

Inhoud en formaat van een tokenResponse

Een tokenResponse is gebaseerd op RFC 6749 en bevat de volgende attributen:

Voorbeeld van een tokenResponse:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "gbc.contextcode.MEDICATIE patient/MedicationRequest.s"
}

HTTP statuscodes

Zie RFC 6749.

getCapabilitiesGBC

Inhoud en formaat van een capabilitiesRequest

TODO request

Inhoud en formaat van een capabilitiesResponse

TODO response

HTTP statuscodes

TODO statuscodes

core-FHIR-interactieGBC

Inhoud en formaat van een core-FHIR-Request

Zie:

• https://twiin-afsprakenstelsel.scrollhelp.site/ta130/10-3-1-twiin-01-send-notification-task#id-10.3.1%7CTwiin-01%7CSendNotificationTask-Requestmessage

• https://twiin-afsprakenstelsel.scrollhelp.site/ta130/10-3-2-twiin-02-cancel-notification-task#id-10.3.2%7CTwiin-02%7CCancelNotificationTask-Requestmessage

De waarde van de base-URL van de FHIR endpoints die het GTK biedt ( [base] dus ), dient voor alle FHIR-interacties gelijk te zijn aan:

• https://<FQDN>{</path extension>}/fhir/<fhir-version>/<twiin-interface-version>{/<app-id>}

De waarde van <fhir-version> is dan bijvoorbeeld "STU3", "R4" of "R5".

De waarde van <twiin-interface-version> is de major versie van de Technische Kern binnen Twiin die door het GTK wordt geïmplementeerd. Deze is gelijk aan “v1”.

Voor instance-level interacties (bijvoorbeeld een FHIR-read of een FHIR-update) dient het <app-id> van de GBZ-applicatie die fungeert als Resource Server te worden toegevoegd aan de base-URL. Voor FHIR-search interacties mag een <app-id> ook worden toegevoegd, maar is het niet verplicht. Een <app-id> die wordt gebruikt in de base-URL dient overeen te komen met het app-id dat is opgenomen in de audience van het gebruikte AORTA access_token.

Inhoud en formaat van een core-FHIR-Response

Zie:

• https://twiin-afsprakenstelsel.scrollhelp.site/ta130/10-3-1-twiin-01-send-notification-task#id-10.3.1%7CTwiin-01%7CSendNotificationTask-Responsemessage

• https://twiin-afsprakenstelsel.scrollhelp.site/ta130/10-3-2-twiin-02-cancel-notification-task#id-10.3.2%7CTwiin-02%7CCancelNotificationTask-Notificationresponse

HTTP statuscodes

TODO statuscodes

Aanvullende eisen