Registratie afnemende datadienst

Om een nieuwe afnemende datadienst te registeren dient eerst een nieuwe dienstengroep aangemaakt te worden:

Deze groep heeft alleen een organisatorische functie.

Voor het registreren van een nieuwe afnemende datadienst binnen de groep kan de knop "Voeg afnemende datadienst toe" worden gebruikt:

Deze zal het volgende scherm tonen:

In dit voorbeeld worden de volgende velden gevuld.

Tip	Bij de velden met een asterisk (*) worden de beschikbare keuzes mogelijk beperkt door de verstrekkende datadienst.

Naam

Wordt gebruikt om de energieconsument te tonen voor welke datadienst er toestemming wordt verleend.

Toelichting

Deze tekst geeft een korte omschrijving waarvoor de datadienst bedoeld is.

Verstrekkende datadienst koppelen

Selecteer hier de verstrekkende datadienst die binnen het toestemmingsplatform is geregistreerd door een verstrekkende data leverancier.

Redirect URL

URL waarop de applicatie aangeroepen wordt als de OAuth flow voltooid is (succesvol of niet).

Gebruiker type

Aangeven voor welk type gebruikers deze dienst beschikbaar is (Particulier of Zakelijk of beide)

Vereiste betrouwbaarheidsniveau *

Het minimale betrouwbaarheidsniveau van het identificatiemiddel van de energieconsument bij het geven van toestemming, bijvoorbeeld om two-factor authenticatie verplicht te stellen.

Type verstrekking *

Het soort toestemming dat aan de energieconsument moet worden gevraagd: eenmalig gebruik of doorlopende toestemming, al dan niet met einddatum.

Ondersteunde aansluiting types *

De aansluitingstypes waarvoor data wordt gevraagd (elektriciteit en/of gas).

Status *

De status (actief of inactief) waarmee de datadienst aangemaakt wordt. Een inactieve dienst kan (nog) niet gebruikt worden.

Client ID *

Het client ID van de OAuth client horende bij deze dienst *

Public key *

De (RSA of EC) public key in PEM-format. Deze kan ook op een later moment gewijzigd worden.

Public key ID *

Het ID van de public key ('kid' in client assertion)

OAuth configuratie

De gegevens voor de OAuth configuratie kan worden gevonden op: https://www.mijnenergiedata.nl/autorisatieregister/.well-known/openid-configuration.

Deze configuratie is leidend voor het bepalen van de juiste URL’s, issuer van tokens, JWK’s URI etc. De meeste OAuth libraries werken ook op basis van deze configuratiegegevens.

Eenmalige toestemming geven en data ophalen (overzicht)

Technisch sequence diagram van het geven van toestemming en vervolgens ophalen van data vanuit het perspectief van de afnemende partij.

In het bovenstaande sequence diagram worden vier actoren onderscheiden:

Energy Consumer Browser: De browser van de energieconsument. Deze wordt door een OIDC-flow heen geleid, met als eindresultaat het ophalen van de gevraagde data.
Consuming Service: De afnemende dienst. Dit kan een App zijn, een SPA of een applicatie met een aparte back-end. Voor een deel van de benodigde functionaliteit biedt EDSN de applicatie "generiek afnemen" aan. Het gebruik hiervan wordt aanbevolen, maar is niet verplicht.
Consent Platform: het toestemmingsplatform zoals aangeboden door EDSN. Dit bestaat uit verschillende technische onderdelen, maar logisch gezien worden deze als één geheel beschouwd, dus in dit diagram als één lane getoond.
Data Service: de verstrekkende datadienst. Met de juiste autorisaties kan hier de gevraagde data opgehaald worden.

Starten toestemmingsflow via redirect URI

Na registratie van de afnemende dienst kan aan consumenten toestemming gevraagd worden om hun data uit de gekozen datadienst te delen. Hiervoor wordt het OpenID Connect (OIDC) protocol gebruikt. Om de toestemmingsflow te starten moet de consument worden doorgestuurd naar een speciaal opgebouwde URL. Verderop in het document wordt beschreven hoe.

Callback URL voor ontvangen toestemming

De callback URL waarop de OAuth flow het resultaat zal terugsturen kan worden ingesteld binnen het toestemmingsplatform (zie: Registratie afnemende datadienst). De browser van de consument wordt hiernaartoe doorverwezen na afronding van de toestemmingsflow.

Indien toestemming is verleend zal de callback URL worden aangeroepen met een Authorization Code Grant (<applicatie callback url>?code=<code>&state=<state>; OpenAPI specificatie). Daarbij zal de Authorization Code als URL-parameter code worden doorgegeven. De state-parameter zal overeenkomen met de waarde die bij de initiële redirect was gekozen. Deze kan gebruikt worden om lokaal bewaarde informatie weer op te halen (zoals bijvoorbeeld de code_verifier van de PKCE flow).

Indien er geen toestemming is verleend of als er een fout is opgetreden dan zal de callback URL worden aangeroepen met de URL-parameters error en error_description.