Document toolboxDocument toolbox

MO-24 Duiding van fouten

Owned by Kailesh Bansi (Deactivated)
Last updated: Jul 04, 2023Version comment
14 min read

1. Probleemstelling


Out of scope (voor nu): tracing en logging

Probleemstelling: Het voordoen van een onderbreking tijdens een poging tot het ophalen van informatie leidt tot (mogelijke) weergave van foutmeldingen aan de kant van de PGO, daarentegen

zijn deze foutmeldingen onduidelijk en niet herleidbaar tot de oplossing. Dit komt doordat MedMij gericht is op dataminimalisatie en de DVP niet onnodig inzicht krijgt van de relatie tussen Persoon en Aanbieder.

Assignee: Kailesh

De prioriteit voor dit probleem wordt deels ondersteund door het artikel van Skipr (2022). Hierin wordt namelijk gesteld dat het '55 procent van de ondervraagden niet gelukt is om gegevens van de huisarts op te halen. Door technische problemen en onduidelijkheid kwamen zij niet verder in de systemen.'

Een simpel voorbeeld: 

2. Koppelingen

De mogelijkheid was aanwezig dat de issue kon aansluiten op behoeftes van het validatieloket betreft de logging van foutmeldingen/errors. Daarentegen valt deze behoefte na aanvullende gesprekken buiten de scope van dit issue.

De behoefte van het validatieloket is het loggen van fouten van verschillende interacties tussen de componenten van MM, DVA, DVP, XIS, PGO, waarna fouten uit de logs worden gefilterd en opgelost. Om het feit dat dit issue gaat over het duiden van fouten richting de persoon/PGO is een log/trace etc. overtollige informatie om te tonen aan de persoon. Het vervolg hierop is MO-52 (logging en monitoring).  Eerdere RFC:  https://vzvz.atlassian.net/wiki/x/Pp4JC


3. Huidige situatie

De huidige situatie kent verschillende onderdelen voor het succesvol ophalen van informatie bij de Aanbieder (zie Afbeelding 1). Daarentegen kunnen er overgangen mislukken wat leidt tot een weergave van een foutmelding. Deze foutmeldingen geven niet duidelijk aan wie of wat verantwoordelijk is voor deze melding en wat een oplossing zou kunnen zijn.


Afbeelding 1: Een globale weergave van de interacties tussen de PGO-DVP-DVA-DigiD en XIS voor de functie Verzamelen

  1. De DVP Server start de flow door in de User Agent van de Persoon de mogelijkheid te presenteren om één of meerdere Gegevensdiensten bij een zekere Aanbieder te verzamelen. Uit de Aanbiederslijst weet de DVP Server welke Gegevensdiensten door een Aanbieder aangeboden worden. Desgewenst worden de Gegevensdienstnamen uit de Gegevensdienstnamenlijst gebruikt.

  2. De Persoon maakt expliciet zijn selectie en laat de User Agent een authorization request sturen naar de Authorization Server. Het adres van het authorization endpoint komt uit de Aanbiederslijst. De redirect_uri geeft aan waarnaartoe de Authorization Server de User Agent verderop moet redirecten (met de authorization-code). Het authorization request mag desgewenst, onder voorwaarden, meerdere Gegevensdiensten van de Aanbieder bevatten. Binnen het autorisatieproces valt ook het eerst mogelijke moment waarop de Dienstverlener aanbieder moet instaan dat voor de Gegevensdienst waartoe een verzoek behoort de Aanbieder de gezondheidsgegevens beschikbaar heeft.

  3. Nadat de Dienstverlener aanbieder een autorisatie heeft afgegeven aan de Dienstverlener persoon is de DVP Server gereed om één of meerdere verzoeken om de gezondheidsinformatie naar de Resource Server te sturen, nadat hij de Persoon eventueel nog nadere keuzes heeft laten maken. Het adres van de juiste resource endpoints haalt hij uit de Aanbiederslijst. Hij plaatst telkens het access-token in het bericht en zorgt ervoor dat in het bericht geen BSN is opgenomen.

  4. De Resource Server controleert bij ieder verzoek of het ontvangen token recht geeft op de gevraagde resources en haalt deze (al dan niet) bij achterliggende bronnen op. Dan breekt het laatst mogelijke moment aan waarop de Resource Server ervoor moet instaan dat voor de Gegevensdienst waartoe een verzoek behoort de Aanbieder de gezondheidsgegevens beschikbaar heeft. Is dat zo, dan verstuurt de Resource Server deze in een resource response naar de DVP Server.

  5. De DVP Server bewaart de ontvangen gezondheidsinformatie in het persoonlijke dossier. De DVP Server bevraagt de Resource Server daarna mogelijk opnieuw, eventueel na nieuwe interactie met de Persoon. Zolang het access-token geldig is, kan dat.


Afbeelding 2. Happyflow die de Persoon doorloopt voor het verzamelen van zijn/haar aanwezige gegevens voor de geselecterde gegevensdienst

De verschillende schermen die de Persoon ziet zijn in Afbeelding 2 weergegeven. Deze happyflow kunnen bij de transities worden onderbroken. Deze onderbreking moet teruggekoppeld worden aan de Persoon.

4. Mogelijke problemen en locaties

In dit hoofdstuk worden de verschillende stappen in de flow beschreven met daarbij de fouten en foutschermen die zich voor kunnen doen. Deze fouten varieren van 404 fouten die worden veroorzaakt door een onbereikbare server tot een geannuleerd verzoek door de Persoon. De foutpagina's naast de 404 pagina zijn gebaseerd op de responses van OAuth 2.0.

4.1. Onbereikbaarheid

  • Redirect_uri (vanuit PGO) AS DVA onbereikbaar → foutscherm van browser (404)

  • Redirect_uri (vanuit AS DVA) DigiD onbereikbaar → foutscherm van browser (404)

  • Redirect_uri (vanuit DigiD) AS DVA onbereikbaar → foutscherm van browser (404)

  • Redirect_uri (vanuit AS DVA) PGO onbereikbaar → foutscherm van browser (404)

4.2. Fouten bij DigiD

  • Technisch probleem → foutscherm van DigiD → Contact opnemen met DigiD

  • Fout in authenticatie bij DigiD → foutscherm van DigiD → Contact opnemen met DigiD

  • Fout bij uitwisseling persoonsgegevens met DigiD → foutscherm van AS DVA → Contact opnemen met (Dienstverlener) aanbieder en/of DigiD

  • Annulering Authenticatie bij DigiD → foutscherm van AS DVA → Gegevens mogelijk doorzetten naar PGO?

4.3. Fouten bij DVA

  • Technisch probleem → foutscherm van AS DVA → Contact opnemen met (Dienstverlener) aanbieder

  • Onbeschikbaarheid gegevens → foutscherm van AS DVA → Contact opnemen met (Dienstverlener) aanbieder → Gegevens mogelijk doorzetten naar PGO?

  • Annulering bij AS DVA → foutscherm van de DVP → Detailgegevens mogelijk doorzetten naar PGO?

4.4. Fouten bij PGO

  • Fout bij uitwisseling met DVA → foutscherm van de DVP

De happy flow loopt van 1A tot en met 4A.

Los van de 404 fouten, die voortkomen uit onbereikbaarheid en DVAuthn fouten zijn de volgende situaties mogelijk:

1B: Redirect naar DVA (HTTP 200), door foutieve Client-id en/of redirect-uri

1C: Redirect naar DVA geeft fout van andere parameters dan bij 1B, zorgt voor redirect naar DVP met HTTP 302 met Invalid request

2B: Redirect naar PGO (HTTP 302, met access_Denied), nadat op landingspagina bij de DVA is geannuleerd

3B: DVA toont foutmelding, nadat de authenticatie bij DigiD is gestopt om welke reden dan ook

4B: Op de toestemmingsverklaring is voor annuleren gekozen, deze situatie kan ook voorkomen nadat bij 3B is gekozen om nogmaals te annuleren.



5. Oauth 2.0 foutcodes (Authorization- Token en Request endpoints)

In dit hoofdstuk worden de foutcodes beschreven met daarbij verschillende error descriptions. Door gebruik te maken van error descriptions is het mogelijk beter onderscheid te maken tussen bepaalde situaties waar dezelfde foutcode voorkomt. Dit heeft meerdere voordelen, namelijk de Persoon weet wat er fout gaat en wat hij/zij kan doen. Daarnaast kunnen Deelnemers gerichter het probleem oplossen. 


Fout

Foutmelding Header

Foutmelding Body

Foutieve (bestaat niet in de administratie van DVZA) Subscription_id in URL

HTTP 404 Not Found

“not found”

Foutieve (bestaat wel in de administratie van DVZA, maar is niet van de patient) Subscription_id in URL

HTTP 403 Forbidden

“forbidden”

Lege of geen Subscription_id parameter in URL

HTTP 400 Bad request

"bad_request"

Geen end_date parameter

HTTP 400 Bad Request

“bad_request”

Foutieve of lege end_date parameter

HTTP 422 Unprocessable Entity

"wrong date"

BRON: Foutmeldingen 1.5.0 voor subscription


Adherent aan deze soorten foutmeldingen kunnen er code ranges worden gebruikt om de specifieke fout aan te duiden. 'A RangeError is thrown when trying to pass a value as an argument to a function that does not allow a range that includes the value.'

5.1. Authorization endpoint

 RFC 6749 4.1 Authorization Code Grant

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

+----------+ | Resource | | Owner | | | +----------+ ^ | (B) +----|-----+ Client Identifier +---------------+ | -+----(A)-- & Redirection URI ---->| | | User- | | Authorization | | Agent -+----(B)-- User authenticates --->| Server | | | | | | -+----(C)-- Authorization Code ---<| | +-|----|---+ +---------------+ | | ^ v (A) (C) | | | | | | ^ v | | +---------+ | | | |>---(D)-- Authorization Code ---------' | | Client | & Redirection URI | | | | | |<---(E)----- Access Token -------------------' +---------+ (w/ Optional Refresh Token) Note: The lines illustrating steps (A), (B), and (C) are broken into two parts as they pass through the user-agent. Figure 3: Authorization Code Flow


5.1.1. Request

  1. Redirect_uri en/of client_id niet meegestuurd bij het verzenden van het request, of redirect_uri niet url_encoded, of redirect_uri en/of client_id niet een juiste waarde (niet bekend, of niet behorend bij opgegeven client_id).                   

    1. DVA logt de fout. DVA biedt een scherm dat voor de Persoon zichtbaar is.   

    2. Resultaat: HTTP 400, inclusief een beschrijving van het probleem

  2. Een missend attribuut (response_code, state, scope) bij het verzenden van het request.

    1. DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding.

    2. Resultaat: HTTP 302, error = invalid_request, error_description = code in de range 100 (response_code = 101,  state = 102, scope = 103), state (indien meegestuurd)

  3. Toegang aan DVP is niet verleend (DVP→ OCL = toegang geweigerd/blacklist van DVP)

    1. DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding.

    2. Resultaat: HTTP 302, error = unauthorized_client, error_description = code 200

  4. Scope bevat geen of foutieve aanbieder-gegevensdienst-combinaties

    1. DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding.

    2. Resultaat: HTTP 302, error =invalid_scope,  error_description = code 201

  5. Technische error aan de kant van de DVA.

    1. DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding.

    2. Resultaat: HTTP 302, error = server_error,  error_description = code 202

  6. Toegang aan de gebruiker is niet verleend door tijdelijke onderhoud of overloading

    1. DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding.

    2. Resultaat: HTTP 302, error = temporarily_unavailable,  error_description = code 203

5.1.2. Functionaliteit

  1. Persoon annuleert het authorization request
    DVA en DVP loggen de fout. DVP biedt een scherm aan Persoon met de foutmelding dat de authenticatie is gestopt. Extra informatie, zoals annulering of geen toestemming wordt niet verstrekt, aangezien dit de behandelrelatie zou kunnen aantonen bij de DVP. 

    1. Resultaat: HTTP 302, error = access_denied

  2. Toegang aan de gebruiker (en daarmee DVP) tot gegevens is niet verleend (DVP→ DVA en negatieve beschikbaarheidstoets)
    Resultaat: HTTP 302, error = access_denied, error_description = code 40x

    1. 401, Aanbieder weigert gegevens te delen van personen.

    2. 402, Aanbieder weigert gegevens te delen van de Persoon

5.2. Access token endpoint

 Access token 4.1.3

The client requests an access token from the authorization server's token endpoint by including the authorization code received in the previous step. When making the request, the client authenticates with the authorization server. The client includes the redirection URI used to obtain the authorization code for verification.


De interactie met deze interface endpoint vindt als backchannel verkeer plaats, zodoende worden er geen berichten aan de Persoon getoond.

5.2.1. Response

  1. Request mist een vereiste (header) parameter, bevat een niet-ondersteunde (header) parameter, herhaalt een parameter, gebruikt meer dan één methode voor authenticatie, of is op een andere wijze misvormd.  

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error = invalid_request

  2. Client authenticatie mislukt.

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error =  invalid_client

  3. Authorization grant of refresh token is onjuist, verlopen, ingetrokken of komt niet overeen met de URI uit de autorisatie request.

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error = invalid_grant  

  4. De geauthentiseerde cliënt is niet geautoriseerd deze grant type te gebruiken.

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error = unauthorized_client

  5. Authorisatie grant type wordt niet ondersteund door de authorisatie server

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error = unsupported_grant_type

  6. Scope bevat geen of foutieve aanbieder-gegevensdienst-combinaties

    1. DVA en DVP loggen de fout.

    2. Resultaat: HTTP 400, error = invalid_scope

5.3. Resource interface

 Resource owner 4.3


+--------+ +---------------+ | |--(A)- Authorization Request ->| Resource | | | | Owner | | |<-(B)-- Authorization Grant ---| | | | +---------------+ | | | | +---------------+ | |--(C)-- Authorization Grant -->| Authorization | | Client | | Server | | |<-(D)----- Access Token -------| | | | +---------------+ | | | | +---------------+ | |--(E)----- Access Token ------>| Resource | | | | Server | | |<-(F)--- Protected Resource ---| | +--------+ +---------------+ Figure 1: Abstract Protocol Flow

The abstract OAuth 2.0 flow illustrated in Figure 1 describes the interaction between the client, resource owner, authorization server, and resource server (described in [RFC6749]). The following two steps are specified within this document: (E) The client requests the protected resource from the resource server and authenticates by presenting the access token. (F) The resource server validates the access token, and if valid, serves the request


De interactie met deze interface endpoint vindt als backchannel verkeer plaats, zodoende worden er geen berichten aan de Persoon getoond. 

5.3.1. Response

Mocht het uitsturen van een request richting de resource server mislukken reageert deze met: 

  1. Request mist een vereiste (header) parameter, bevat een niet-ondersteunde (header) parameter of parameterwaarde, gebruikt meer dan één methode voor het doorgeven van een access_token, of is op een andere wijze misvormd.                                     

    1. DVA en DVP loggen de fout. 
      Resultaat: HTTP 400, error = invalid_request

  2. Access_token is verlopen, ingetrokken, vervormd of om een andere reden niet geldig.                                                                               

    1. DVA en DVP loggen de fout. 
      Resultaat: HTTP 401, error = invalid_token

  3. Scope die is verbonden aan het meegezonden access_token niet toereikend voor de uitvoering van het resource request.                                 

    1.  DVA en DVP loggen de fout. 
      Resultaat: HTTP 403, error = insufficient_scope


FHIR resource codes opgesteld door Nictiz. Deze resources foutcodes kunnen zich voordoen bij het ophalen van de resource bundels bij de resource server. 


In general, most FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues) will result in one of these HTTP status codes:

  • 400 Bad Request - resource could not be parsed, search could not be processed or basic FHIR validation rules failed

  • 401 Unauthorized - authorization is required for the interaction that was attempted (usually emitted by the authorization server)

  • 403 Forbidden - the server was unable to execute the search, due to an authorization failure (usually emitted by the resource server)

  • 404 Not Found - resource type not supported, or not an FHIR endpoint

  • 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rule

6. Wireframes

In dit hoofdstuk worden de wireframes getoond die deelnemers zouden kunnen gebruiken voor de verschillende probleemsituaties.