Document toolboxDocument toolbox

(MedMij Afsprakenstelsel 2.1.0B) Logging interface

Owned by Martin Wilmink
Jan 30, 2024
8 min read

Voor het uitvoeren van monitoring en het opstellen van rapportages moet MedMij beschikken over goede loggegevens van alle deelnemers. Deze pagina beschrijft welke gebeurtenissen moeten worden vastgelegd, aan welke eisen logregels en verzamelingen van logregels moeten voldoen, hoe deze aangeleverd moeten worden en welke verantwoordelijkheden de verschillende rollen hebben.

Gebeurtenissen


In bovenstaande plaat staat de functie Verzamelen uitgewerkt, inclusief de momenten waarop iets gelogd moet worden. Voor Abonneren en Delen moeten dezelfde gebeurtenissen worden vastgelegd.

  1. send_authorization_request: de DVP logt het versturen van een authorization request naar de DVA.
  2. receive_authorization_request: de DVA logt het ontvangen van een authorization request van de DVP.
  3. show_landing_page: de DVA logt het tonen van de landingspagina.
    1. authorization_request_error & show_authorization_request_error_page: in plaats van het tonen van de landingspagina logt de DVA het ontvangen van een incorrecte client_id en/of redirect_uri en toont een foutpagina, ook dit wordt vastgelegd.
    2. send_authorization_request_error: in plaats van het tonen van de landingspagina logt de DVA het ontvangen van incorrecte parameters
  4. send_authentication_request: de DVA logt het versturen van een authentication request naar de DVAuthN.
    1. send_authorization_cancellation: in plaats van het sturen van een authentication request naar de DVAuthN stuurt de DVA een authorization cancellation naar de DVP. De DVA moet deze gebeurtenis vastleggen.
  5. receive_authentication_response: de DVA logt het ontvangen van een authentication response van de DVAuthN.
    1. receive_authorization_cancellation: in plaats van een authentication response ontvangt de DVA een authorization cancellation van de DVAuthN en logt deze gebeurtenis.
    2. receive_authentication_error: in plaats van een authentication response ontvangt de DVA een authentication error van de DVAuthn en logt deze gebeurtenis.

  6. send_artifact_resolution_request: de DVA logt het versturen van een artifact resolution request naar de DVAuthN.

  7. receive_artifact_response: de DVA logt het ontvangen van een artifact response.
    1. receive_artifact_request_error & show_authentication_error_page: De DVA ontvangt een negatief resultaat op het authenticatie proces, logt dit en toont een foutpagina, ook dit wordt vastgelegd.
  8. result_availability_check: indien op dit moment de beschikbaarheids- of ontvankelijkheidstoets wordt uitgevoerd, dan logt de DVA het resultaat hiervan.
    1. availability_check_error & show_availability_check_error_page: De DVA logt een fout in de beschikbaarheids- of ontvankelijkheidstoets en toont een foutscherm met de mogelijkheid terug te keren naar de DVP. Ook het tonen van het scherm wordt gelogd.
  9. show_consent_page: de DVA logt het tonen van de toestemmings- of bevestigingsverklaring.
  10. receive_consent: de DVA logt het verkrijgen van de toestemming.
  11. send_authorization_response: de DVA logt het versturen van een authorization response.
    1. send_authorization_cancellation:  in plaats van het sturen van een authorization response naar de DVP stuurt de DVA een authorization cancellation naar de DVP. De DVA moet deze gebeurtenis vastleggen.
  12. receive_authorization_response: de DVP logt het ontvangen van een authorization response.
  13. send_token_request: de DVP logt het versturen van een token request.
  14. receive_token_request: de DVA logt het ontvangen van een token request.
  15. result_availability_check: indien op dit moment de beschikbaarheids- of ontvankelijkheidstoets wordt uitgevoerd, dan logt de DVA het resultaat hiervan.
    1. availability_check_error & send_availability_check_error: De DVA logt de fout in de beschikbaarheids- of ontvankelijkheidstoets en logt ook dat het de fout naar de DVP stuurt.
  16. send_token_response: de DVA logt het versturen van een token response.
    1. send_token_request_error: in plaats van het sturen van een token response naar de DVP stuurt de DVA een token request error. De DVA moet deze gebeurtenis loggen.
  17. receive_token_response: de DVP logt het ontvangen van een token response.
    1. receive_availability_check_error: in plaats van een token response ontvangt de DVP een availability check error van de DVA en logt deze gebeurtenis.
    2. receive_token_request_error:  in plaats van een token response ontvangt de DVP een token request error van de DVA en logt deze gebeurtenis.
  18. send_resource_request: de DVP logt het versturen van een resource request.
  19. receive_resource_request: de DVA logt het ontvangen van een resource request.
  20. result_availability_check: indien op dit moment de beschikbaarheids- of ontvankelijkheidstoets wordt uitgevoerd, dan logt de DVA het resultaat hiervan.
    1. availability_check_error & send_availability_check_error: De DVA logt de fout in de beschikbaarheids- of ontvankelijkheidstoets en logt ook dat het de fout naar de DVP stuurt.
  21. result_gathering_information: de DVA logt welke gegevens opgehaald konden worden en welke niet.
  22. send_resource_response: de DVA logt het versturen van een resource response.
    1. send_resource_request_error: in plaats van het sturen van een resource response naar de DVP stuurt de DVA een resource request error naar de DVP. De DVA moet deze gebeurtenis vastleggen.
    2. send_resource_error_response: in plaats van het sturen van een resource response naar de DVP stuurt de DVA een resource error response naar de DVP. De DVA logt dat de gegevens niet gevonden of verstuurd konden worden.
  23. receive_resource_response: de DVP logt het ontvangen van een resource response.
    1. receive_availability_check_error:  in plaats van een resource response ontvangt de DVP een availability check error van de DVA en logt deze gebeurtenis.
    2. receive_resource_request_error: in plaats van een resource response ontvangt de DVP een resource request error van de DVA en logt deze gebeurtenis.
    3. receive_resource_error_response: in plaats van een resource response ontvangt de DVP een availability resource error response van de DVA en logt deze gebeurtenis.


Verantwoordelijkheden

Waar in deze uitwerking gesproken wordt over een UUID verwachten wij dat deelnemers UUIDv4 gebruiken.

1.Verzamelingen van logregels worden in het JSON formaat bij MedMij aangeboden. De verzamelingen worden met een HTTP POST request naar de endpoint van MedMij gestuurd.

core.logint.200

2.

Alle aan te leveren logregels bevatten een event-object met een vaste set aan attributen:

  • type
    een vaste code per gebeurtenis, te kiezen uit de lijst hierboven.
  • location
    De hostname van deelnemer die de logregel vastlegt.
  • datetime
    De datum, het tijdstip en de tijdzone van de gebeurtenis, vastgelegd in het formaat "2023-03-28T22:14:23.618+01:00".
  • session_id
    Het identificerende kenmerk van de sessie bij de deelnemer, bij voorkeur een UUID.
  • trace_id
    Het identificerende kenmerk van het proces waarbinnen de stap wordt uitgevoerd, vastgelegd als UUID.
Voorbeeld event-object binnen logregel 
{
	"event": {
  		"type": "send_authorization_request",
  		"location": "mijn.pgo.nl",
  		"datetime": "2023-03-28T22:14:23.618+01:00",
  		"session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
  		"trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  	 }
 }

core.logint.201

3.

De logregels van alle verzonden en ontvangen verzoeken bevatten een request-object met een vaste set aan attributen:

  • id
    Het unieke identificerende kenmerk (UUID) van het verzoek dat door versturende en ontvangende partij gebruikt wordt.
  • method
    De gebruikte http method.
  • client_id
    De hostname van de verzender van het verzoek.
  • server_id
    De hostname van de ontvanger van het verzoek.
  • uri
    De URI waar het verzoek naartoe wordt gestuurd.
Voorbeeld request-object binnen logregel 
{
	"event": { 
		"type": "send_authorization_request", 
		"location": "mijn.pgo.nl", 
		"datetime": "2023-03-28T22:14:23.618+01:00", 
		"session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb", 
		"trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
	}, 
	"request": { 
		"id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488", 
		"method": "get", 
		"client_id": "mijn.pgo.nl", 
		"server_id": "as.dva.nl", 
		"uri": "https://api.as.dva.nl/2.0.0/authorize"
	 }
 }

core.logint.202

4.

In aanvulling op core.logint.201 moeten bij een authorization request de volgende attributen aan het request-object worden toegevoegd:

  • provider_id
    Het identificerende kenmerk (MedMij Aanbiedersnaam) van de betrokken aanbieder.
  • response_type
    Deze heeft, zolang binnen het MedMij netwerk alleen gebruikgemaakt wordt van de OAuth2 Authorization Code Grant, altijd de waarde 'code'.
  • redirect_uri
    De URI waar het resultaat naartoe gestuurd moet worden. Deze wordt gebruikt voor de redirect terug naar de DVP.
  • state
    De OAuth2 state parameter.
Voorbeeld Authorization request-object binnen logregel 
{
  "event": {
    "type": "send_authorization_request",
    "location": "mijn.pgo.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "request": {
    "id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "method": "get",
    "client_id": "mijn.pgo.nl",
    "server_id": "api.dva.nl",
    "uri": "https://api.dva.nl/2.0.0/authorize",
    "provider_id": "een.huisarts@medmij",
    "response_type": "code",
    "redirect_uri": "https://mijn.pgo.nl/medmij",
    "state": "ipcxyhlbjtvduydtneoaflwiismwxfmj"
  }
}

core.logint.203

5.

In aanvulling op core.logint.201 wordt bij een Artifact resolution request het volgende attribuut aan het request-object toegevoegd:

  • request_type
    Altijd de waarde 'SAML_assertion'
Voorbeeld Authentication request-object binnen logregel 
{
  "event": {
    "type": "send_artifact_resolution_request",
    "location": "api.dva.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "request": {
    "id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "method": "get",
    "client_id": "api.dva.nl",
    "server_id": "digid.nl",
    "uri": "https://api.as.dva.nl/2.0.0/authorize",
    "request_type": "SAML_assertion"
  }
}

core.logint.204

6.

In aanvulling op core.logint.201 worden bij een token request de volgende attributen aan het request-object toegevoegd:

  • grant_type
    De waarde moet 'authorization_code' of 'refresh_token' zijn, waarbij de laatste alleen gebruikt mag worden bij het uitvoeren van een langdurige toestemming.

Aanvullend legt alleen de DVP bij token requests de onderstaande attribuut vast:

  • initiated_by
    De waarde moet 'person' of 'machine' zijn, waarbij de laatste alleen gebruikt mag worden bij automatisch verzamelen.
Voorbeeld Token request-object voor DVP binnen logregel 
{
  "event": {
    "type": "send_token_request",
    "location": "mijn.pgo.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "request": {
    "id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "method": "get",
    "client_id": "mijn.pgo.nl",
    "server_id": "api.dva.nl", 
    "uri": "https://api.dva.nl/2.0.0/authorize",
    "grant_type": "authorization_code",
    "initiated_by": "person"
  }
}
Voorbeeld Token request-object voor DVA binnen logregel 
{
  "event": {
    "type": "receive_token_request",
    "location": "api.dva.nl",
    "datetime": "2023-09-28T22:14:36.618+01:00",
    "session_id": "d7382884-865e-4185-8347-2c4922d8ef73",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "request": {
    "id": "1p5d6cb2-a2c0-4893-bd97-240621c3e582",
    "method": "get",
    "client_id": "mijn.pgo.nl",
    "server_id": "api.dva.nl",
    "uri": "https://api.dva.nl/2.0.0/token",
    "grant_type": "authorization_code",
  }
}

core.logint.205

7.

In aanvulling op core.logint.201 worden bij een resource request de volgende attributen aan het request-object toegevoegd:

  • provider_id
    Het identificerende kenmerk (MedMij Aanbiedersnaam) van de betrokken aanbieder.
  • service_id
    Het identificerende kenmerk (nummer) van de opgevraagde gegevensdienst.
Voorbeeld Resource request-object binnen logregel 
{
  "event": {
    "type": "send_resource_request",
    "location": "mijn.pgo.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "request": {
    "id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "method": "get",
    "client_id": "mijn.pgo.nl",
    "server_id": "api.dva.nl",
    "uri": "https://api.dva.nl/2.0.0/authorize",
    "provider_id": "een.huisarts@medmij",
    "service_id": 49
  }
}

core.logint.206

8.

De logregels van alle verzonden en ontvangen antwoorden bevatten een response-object met een vaste set aan attributen:

  • request_id
    De id van het request waar het antwoord bij hoort.
  • status
    De HTTP status code.
Voorbeeld response-object binnen logregel 
{
  "event": {
    "type": "send_authorization_response",
    "location": "as.dva.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "response": {
    "request_id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "status": 200
  }
}

core.logint.207

9.

De logregels van alle fouten in het proces bevatten een error-object met een vaste set aan attributen:

  • code
    De waarde van het OAuth2.0 attribuut 'error' worden overgenomen.
  • description
    Omschrijving van de geregistreerde fout. Bij de problemen in de beschikbaarheids- of ontvankelijkheidstoets moeten de waarden no_information_available (bij geen behandelrelatie), invalid_age of blocked worden gebruikt.
Voorbeeld error-object binnen logregel 
{
  "event": {
    "type": "availability_check_error",
    "location": "as.dva.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "error": {
    "code": "access_denied",
    "description": "no_information_available"
  }
}

core.logint.208

10.

In aanvulling op core.logint.208 worden bij request errors de volgende attributen aan het error-object toegevoegd:

  • request_id
    De id van het request waar het antwoord bij hoort.
  • status
    De HTTP status code.
Voorbeeld request-error-object binnen logregel 
{
  "event": {
    "type": "send_availability_check_error",
    "location": "api.dva.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "error": {
    "code": "access_denied",
    "description": "no_information_available",
    "request_id": "8b5d6cb2-a2c0-4893-bd97-240621c3e488",
    "status": 403
  }
}

core.logint.209

11.

De logregels van het type result_gathering_information bevatten een information-object met met daarin een lijst de namen van succesvol opgehaalde data-objecten, een lijst van opgehaalde data-objecten waarvan de waarde leeg is en een lijst van onsuccesvol opgehaalde data-objecten:

 Toelichting

In het zorg domein worden de namen van de FHIR resources gebruikt voor de data-objecten. De FHIR Resources worden per gegevensdienst beschreven in technische uitwerkingen die via de Catalogus te vinden zijn.

Voorbeeld information-object binnen logregel 
{
  "event": {
    "type": "result_gathering_information",
    "location": "api.dva.nl",
    "datetime": "2023-03-28T22:14:23.618+01:00",
    "session_id": "c6a27d45-4316-464e-81e0-48d5dbccacbb",
    "trace_id": "79dc6181-6239-4fdd-ad98-594312aeac71"
  },
  "information": {
    "successful": ["name1", "name2"],
    "empty":  ["name3", "name4"],
    "unsuccessful": ["name5", "name6"]
  }
}

core.logint.210