MAGDA

Inleiding

MAGDA staat voor MAximale GegevensDeling tussen Administraties. MAGDA is een dienst van de Vlaamse overheid. MAGDA ontsluit een brede waaier aan authentieke overheidsbronnen. De MAGDA-connector is vrij uitgebreid en ontsluit een groot aantal beschikbare services.

Protocol

Onboardingsprocedure

Om aan te sluiten op MAGDA, moet de klant (dus de organisatie waarvoor Skryv de applicatie uitwerkt) een specifieke onboardingsprocedure doorlopen. Dit gebeurt per Skryv applicatie en per service die je wil aanspreken. Gedetailleerde info vind je op deze website. Hieronder een beknopt stappenplan.

1. Bepaal welke MAGDA-service je precies wil gebruiken (bv. geefPersoon).

2. Bepaal welke specifieke gegevens je via deze service wil opvragen (bv. domiciiegegevens) en voor welke doeleinden je de gegevens zal gebruiken.

3. MAGDA keurt je aanvraag goed en zet een testconnectie op. Je ontvangt volgende info:

   1. URL endpoint

   2. Key & certificaat (meer info)

   3. Hoedanigheid (IPDC-nummer of aansluitingsnummer)

   4. Uri

4. Je voert 50 test calls uit. MAGDA checkt vervolgens of deze correct zijn uitgevoerd.

5. MAGDA zet een productieconnectie op. Je ontvangt volgende info:

   1. URL endpoint

   2. Key & certificaat (meer info)

   3. Hoedanigheid (IPDC-nummer of aansluitingsnummer)

   4. Uri

6. Je voert nogmaals 50 test calls uit. MAGDA checkt opnieuw of deze correct zijn uitgevoerd.

Veilige communicatie

Om een veilige communicatie tussen Skryv en Magda tot stand te brengen, werken we met asymmetrische cryptografie op basis van een private key (geheim) en een public key (openbaar). Iedere request die we versturen naar Magda wordt versleuteld via onze private key, waarna Magda deze kan decrypteren op basis van onze public key.

De procedure om dit systeem op te zetten, verloopt volgens onderstaand stappenplan, en kan uitgevoerd worden via openSSL. Dit gebeurt per Skryv applicatie en per service die je wil aanspreken.

• De Skryv developer genereert een private/public key pair. De private key blijft geheim en wordt gebruikt om data (zoals JWT-tokens) te ondertekenen. De private key en het wachtwoord ervan worden opgeslagen in AWS Secrets Manager.

• De Skryv developer maakt een CSR (Certificate Signing Request) en stuurt deze naar Magda. De CSR bevat de public key en een handtekening gemaakt met de private key, wat bewijst dat de aanvraag van Skryv komt.

• Magda ontvangt de CSR, valideert de handtekening op basis van de public key en koppelt de public key aan een certificaat. Het certificaat is een formele bevestiging dat de public key valide is en aan de specifieke Skryv applicatie is gekoppeld.

• Magda levert het certificaat af. Dit wordt opgeslagen in AWS Secrets Manager.

• Voor sommige services zoals DOSIS en Documentendienst moet op basis van de keys en het certificaat een .jwks-bestand aangemaakt worden. Dit kan aan de hand van een Python-script dat beschikbaar is bij het Skryv-team. Het .jwks-bestand wordt ter beschikking gesteld aan Magda.

Concreet verloopt de communicatie met Magda op basis van een JWT-token. De private key ondertekent dit JWT-token. Magda gebruikt vervolgens je public key (eventueel uit het .jwks-bestand) om de JWT-token te valideren. Op die manier is Magda er zeker van dat de uitgestuurde request ook effectief door jou is uitgestuurd.

Dependency toevoegen aan pom.xml bestand

Voeg onderstaande dependency toe aan het pom.xml bestand van je applicatie. Dit zorgt ervoor dat de connector code ingeladen wordt bij de build van de applicatie.

 <dependency>
      <groupId>com.skryv.connectors</groupId>
      <artifactId>magda</artifactId>
 </dependency>

Applicatie eigenschappen

Per service moet je enkele applicatie eigenschappen instellen. Deze vallen uiteen in twee delen. Het eerste deel bevat eigenschappen die de toegang regelen. Het tweede deel zijn eigenschappen die de connectie naar de service configureren.

Toegang

Opdat de connector toegang zou krijgen tot de MAGDA service, moet deze beschikken over de volgende informatie. De placeholder {service} moet je telkens vervangen door de specifieke service die je wil implementeren.

• dosis (legacy connector)

• ebox (magda documentendienst)

• gc (ondernemingen - giveCompany)

• ghp

• gp (geefPersoon)

• mobility (mobiliteit)

• poc (kadaster)

• ri (repertorium)

• sme (ondernemingen - geefJaarrekeningen)

• zoekeigendomstoestanden (kadaster)

URL-endpoint

Keys en certificaten

Hoedanigheid

Onderstaand is de default voor alle magda services. In de meeste gevallen wordt dit vervangen door een service specifieke eigenschap.

Uri

Onderstaand is de default voor alle magda services. In de meeste gevallen wordt dit vervangen door een service specifieke eigenschap.

Service specifiek

Toegespitst op de service die je wil gebruiken, voeg je de juiste nog enkele specifieke applicatie eigenschappen toe.

Performantie via resilience4j

Je kan de performantie van de connectie configureren via resilience4j. Klik hier voor meer info over connectoren, performantie en hoe je dit kan configureren.