Interfaces Autorisatie Server GBC

GBC Metadata Interface

getMetadataAS-GBC

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 metadataRequest

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.

Aanvullende eisen

GBC Token Interface

getTokenAS-GBC

Feature informatie

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.

Aanvullende eisen

JSON-LD Interface

getJSON-LDcontextGBC

Feature informatie

Verifiable Credentials in de GBC context maken gebruik van een gedeelde JSON-LD context die de ontologie definieert. Een Verifiable Credential verwijst in het @context attribuut naar een specifieke versie van de JSON-LD context die van toepassing is:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://[aorta-gbc-base-URL]/gbc/context/v1"
  ]
}

Voor het versiebeheer van de context gelden de volgende regels: 

• Toevoegen van nieuwe termen, types of relaties is een minor wijziging en MOET backward compatible zijn. Bestaande credentials blijven geldig.

• Wijzigen van de IRI of het datatype van een bestaande term is een breaking change en vereist een nieuw versienummer.

• Verwijderen van een bestaande term is een breaking change en vereist een nieuw versienummer. 

Verifiers MOETEN credentials accepteren die verwijzen naar een oudere context-versie, tenzij die versie door de stelselhouder is ingetrokken. De stelselhouder publiceert alle actieve context versies.

Namespaces

De GBC context specificeert de volgende namespaces:

• gbc: >> http://aorta.gbc.nl/ (AORTA GBC-specifieke termen)

• schema: >> http://schema.org/ (generieke termen)

Identifiers

Identifiers worden gemodelleerd als geneste objecten met een system en value. De onderliggende linked data representatie hergebruikt schema:PropertyValue uit de http://schema.org vocabulaire. Voor leesbaarheid wordt hiervoor de alias Identifier geïntroduceerd. De veldnamen system en value zijn aliases voor schema:propertyID en schema:value.

Entiteit-types

Relatie-types

Relatie- en attribuut-termen

Inhoud en formaat van een json-ldContextRequest

Een json-ldContextRequest dient te worden verzonden naar de URL die is opgenomen in de @context:

GET /gbc/context/v1 HTTP/1.1
Host: [aorta-gbc-base-URL]
Accept: application/ld+json, application/json; charset=utf-8

NB. de Accept header mag application/ld+json en/of application/json bevatten.

Inhoud en formaat van een json-ldContextResponse

Een json-ldContextResponse bevat de volgende headers:

Content-Type: application/did+ld+json; charset=utf-8
Cache-Control: must-revalidate, max-age=<max-age-context>
Pragma: no-cache

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

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

De body van de json-ldContextResponse bevat de volgende JSON structuur.

{
  "@context": {
    "gbc": "http://aorta.gbc.nl/",
    "schema": "http://schema.org/",
    "HealthcareProvider": "gbc:HealthcareProvider",
    "HealthcareProfessional": "gbc:HealthcareProfessional",
    "HealthcareWorker": "gbc:HealthcareWorker",
    "Patient": "gbc:Patient",
    "ServiceProvider": "gbc:ServiceProvider",
    "Delegation": "gbc:Delegation",
    "DelegationScope": "gbc:DelegationScope",
    "PatientEnrollment": "gbc:PatientEnrollment",
    "Identifier": "schema:PropertyValue",
    "identifier": {
      "@id": "schema:identifier",
      "@container": "@set"
    },
    "system": "schema:propertyID",
    "value": "schema:value",
    "roleCode": {
      "@id": "gbc:roleCode",
      "@type": "http://fhir.nl/fhir/NamingSystem/uzi-rolcode"
    },
    "name": "schema:name",
    "hasDelegation": "gbc:hasDelegation",
    "delegatedBy": "gbc:delegatedBy",
    "scope": "gbc:scope",
    "authorizationRule": "gbc:authorizationRule",
    "authorizedActions": "gbc:authorizedActions",
    "hasEnrollment": "gbc:hasEnrollment",
    "patient": "gbc:patient",
    "enrolledBy": "gbc:enrolledBy",
    "services": "gbc:services"
  }
}

HTTP statuscodes

Zie RFC 6749.

Aanvullende eisen