zal de informatie op https://prod.dosis-burgers.vlaanderen.be/ vervangen

Referentie magda documentendienst/REST diensten documentatie: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1602748845/Token-gebaseerde+diensten#Fase-0%3A-Opzet-bij-de-Token-provider-van-de-Vlaamse-Overheid-(AIV-AAS)

Fasen/topics/stappen te doorlopen

Security (Geosecure OAuth 2.0) (zowel D+N)

algemene uitleg over hoe de api beveiligd is: OAuth 2.0 / client credentials
(https://beta.oauth.vlaanderen.be/authorization/Help/Api/ClientCredentialsGrant)

...

korte uitleg over gebruik van JWK: assymetrische sleutels (ipv client id/client secret)

• codevoorbeelden

  • .NET om JWT (op basis van JWK)JSON Web Token

  • JAVA: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1602748845/Token-gebaseerde+diensten#Code-voorbeeld

• fase 1 van magda docs: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1602748845/Token-gebaseerde+diensten#Fase-0%3A-Opzet-bij-de-Token-provider-van-de-Vlaamse-Overheid-(AIV-AAS)

• Hoe een keypair genereren:

  • https://beta.oauth.vlaanderen.be/authorization/Help/Api/GenerateJsonWebKey

  • nog op zoek gaan naar alternatieve tools: via openssl commando / online tooltje / link naar de RFC https://tools.ietf.org/html/rfc7517
    

...

...

• https://beta.oauth.vlaanderen.be/authorization/Help/Api/ClientCredentialsGrant : schema (overview flow) + obtaining access tokens
  + aanvullen met geosecure info op https://beta.oauth.vlaanderen.be/authorization/Help/Api/ClientAuthentication#private_key_jwt
  => vanaf Incorporation of the JSON Web Token in the body of the request
  

• https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1602748845/Token-gebaseerde+diensten#Aanvraag-HTTP-request => stukje vanaf “aanvraag http request”
  

• Het antwoord dat je van geosecure terugkrijgt = dit is het access token dat je uiteindelijk nodig hebt om effectief een DOSIS api call te kunnen doen:

  • https://oauth.vlaanderen.be/authorization/Help/Api/ClientCredentialsGrant (handling the response)

  • magda versie: https://vlaamseoverheid.atlassian.net/wiki/spaces/MG/pages/1602748845/Token-gebaseerde+diensten#Antwoord-van-de-Authenticatie-en-Autorisatie-Server-(AAS)

DOSIS configuratie

Doel:

• de gewenste IPDC producten moeten geconfigureerd staan in DOSIS:

  • kan reeds op voorhand klaar staan door opzet aansluitingenteam (bvb pakketconfiguratie of aparte IPDC producten)

  • kan ook door de afnemer zelf (deels) geconfigureerd worden:

    • extra ipdc producten toevoegen

    • vlaamse/fasen coden

Producten configureren (in portaal)

...

Todo’s:

...

check de lijst met producten

check of de config per product ok is:

...

welke vlaamse fasen zullen er gebruikt worden

...

volgorde van de vlaamse fasen

...

Enkel voorpakketconfiguratie:

...

doorgaans enkel van toepassing voor dienstenleveranciers:
Voor wijzigingen aan het pakket moet je contact opnemen met onze service desk (link naar een nog te maken Jira service desk formulier).

...

DOSIS API aanroepen

• Basisprincipes uitleggen

  • wat is de dosis bron uri (die je ontving bij onboarding)

    • wordt toegewezen bij aansluiting

    • vormt samen met het eigen dossiernummer de unieke identificatie voor een dossier binnen DOSIS

    • bij elke dossier status wijziging wordt dus de bron uri + dossiernummer doorgestuurd. https://beta.dosis.dev-vlaanderen.be/api/help/model?modelnaam=DossierIdentificatie
      "Identificatie": {
      "Bron": "urn://digitaalvlaanderen.be/applicatie", => namespace vast toegewezen door AIV
      "DossierNummer": "eigen dossiernummer EV" => “eigen referentie”, nummer, … whatever
      },

    • Nota: indien de aansluitende partij met meerdere backend systemen werkt en er daartussen overlap is in de dossiernummers, is het aangewezen om meerdere bron uri’s aan te vragen.
      bvb: systeem voor burgers vs systeem voor ondernemers: beide een dossiernummer “1000” => zorgt voor problemen als je maar 1 enkele bron uri hebt.
      voorbeeld: beter dan om urn://zaventem.be/burgers en urn://zaventem.be/ondernemers” aan te vragen.
      

  • OAuth client

  • begrippenlijst in 't algemeen: …

• minimale API calls voor standaard DOSIS integratie: https://vlaamseoverheid.atlassian.net/wiki/spaces/WPMBP/pages/2536964391/Aanzet+stappenplan+instructies+Aansluiten+op+dossierstatusinformatie+en+notificaties#API-calls

Hoe testen en valideren tijdens de ontwikkeling

TESTEN

Uitleg over hoe de systemen gekoppeld zijn:

• DOSIS BETA is gelinkt met MBP frontend BETA => zit achter een mock OpenID Connect (OIDC) implementatie:
  hier kan je makkelijk met een zelf ingegeven RRN inloggen.
  

• DOSIS TNI is gelinkt met MBP TNI => zit achter ACM-IDM. Enkel aanmelden met sterke authenticatie.
  Gebruiker moet bekend zijn bij ACM-IDM T&I
  

ADVIES: integratie met de BETA omgeving: gebruik GEEN persoonsgevoelige of echte data.
reden: iedereen kan met gelijk welk RRN inloggen op MBP front.
Dit is ook net het voordeel om snel te kunnen testen.=> laagdrempelig om te testen.

OPM: indien je test met persoonsgevoelige (of “echte”) data dan aanbevolen om met TNI te integreren.
Voor burgers: iedere burger kan inloggen via ACM T&I via sterke authenticatie

...

URL MBP front: https://beta.frontend.burgerprofiel.dev-vlaanderen.be/ (BETA)
https://tni.frontend.burgerprofiel.dev-vlaanderen.be/ (TNI)

HOE NAAR PRODUCTIE GAAN

Alvorens naar productie te gaan vragen we een basis set testen op de beta (of TNI) omgeving.

...

Voorbeeld/referentie implementaties

Nodig:

• visuele mapping van velden uit de payload naar schermen van zowel e-loket als MBP : wat komt nu waar te staan?
  

• Voorbeeldjes uitwerken:

  • heel eenvoudig voorbeeld: minimale zaken die naar dosis moet doorsturen (GEEN url, GEEN dossierbeheerder) => heel kort voorbeeldje
    

  • “technisch” voorbeeld: sluit aan op visuele mapping: bvb als payload “dit is het dosssiernummer”, “dit is de omschrijving van je dossier ExtraInformatie.
    + screenshot dan van eloket en MBP front van hoe het getoond wordt (ipv screenshots kan dit ook inloggen zijn met een vast demoprofiel)
    

  • Voorbeelden voor VO-entiteit: vaak 1 specifiek IPDC product:
    Vb: omgevingsvergunning aanvragen, aanvraag van een subsidie.
    

  • Voorbeelden voor lokale besturen: inschrijving als burger bij de gemeente, aanvraag toegang tot recyclagepark,

• DEMO omgeving: propere omgeving zonder veel andere brol:

  • eentje voor VO-demo’s

  • eentje voor LB-demo’s

  • eentje voor technische demo’s

(concreet aantal test RRN’s en KBO nummers)

Doelpubliek

Deze documentatie is bestemd voor lokale besturen, Vlaamse overheidsdiensten en dienstenleveranciers/software-integratoren die dossierstatusinformatie (DOSIS) willen opladen en die informatie via een digitaal loket (Mijn Burgerprofiel, e-loket ondernemers of het Verenigingsloket) beschikbaar willen maken voor hun gebruikers.

Architectuur DOSIS

...

Lees het overzicht van de DOSIS-basisbegrippen

Starten met een aansluiting op DOSIS