MAGDA algemene setup

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.

Bepaal welke MAGDA-service je precies wil gebruiken (bv. geefPersoon).
Bepaal welke specifieke gegevens je via deze service wil opvragen (bv. domiciliegegevens) en voor welke doeleinden je de gegevens zal gebruiken.
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
Je voert 50 test calls uit. MAGDA checkt vervolgens of deze correct zijn uitgevoerd.
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
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.

CODE

 <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 de applicatie beschikken over volgende instellingen.

Algemene instellingen

Of je nu één of meerdere MAGDA-services wil implementeren, onderstaande lijst is een overzicht van algemene, gedeelde eigenschappen geldig over alle services heen.

Eigenschap	Default	Beschrijving
`skryv.aws.mutual-ssl.seed.enabled`	`false`	Indien `true`, dan haalt de applicatie de key en het certificaat op uit de AWS Secrets Manager en slaat deze lokaal in de applicatie op (zie de twee rijen hieronder). Indien `false`, dan neemt de applicatie rechtstreeks de lokaal gedefinieerde key en certificaat zonder eerst AWS Secrets manager te bevragen.
`magda.default.uri`	`''`	URI die de aanroepende applicatie identificeert in de MAGDA SOAP request context.
`magda.default.hoedanigheid`	`''`	IPDC-code die je aansluitingsrechten identificeert.
`legal.logging.appclientid`	`''`	Application client ID for legal logging of MAGDA calls
`legal.logging.unhash-rrn`	`false`	If `true`, logs the raw national registry number instead of a SHA-256 hash

Overzicht services

Overzicht van binnen Skryv beschikbare MAGDA-services. Klik door op de service voor verdere details onder de sectie connectoren > connectoren details > MAGDA gegevensdeling.

{service}	Magda service	SSL (SOAP-services)	Specifieke eigenschappen
`betalingenHandicap`	GeefBetalingenHandicap	gedeeld	nee
`car`	GeefVoertuig	specifiek	nee
`dmfa`	GeefDmfaVoorWerknemers	specifiek	nee
`dosis`	Dossier (legacy)	specifiek	ja
`ebox`	Documentendienst	specifiek	ja
`functies`	GeefFuncties	specifiek	nee
`gc`	GiveCompany	specifiek	nee
`geefDossierHandicap`	GeefDossierHandicap	gedeeld	nee
`gfcv2`	GeefGezinssamenstelling	specifiek	ja
`ghfcv2`	GeefHistoriekGezinssamenstelling	specifiek	ja
`ghp`	GeefHistoriekPersoon	specifiek	ja
`glwp`	GeefLeefLoonPeriodes	specifiek	nee
`gp`	GeefPersoon	specifiek	ja
`handicap`	GeefHandicap	gedeeld	nee
`kindVoordelen`	GeefKindVoordelen	gedeeld	nee
`leefloonbedragen`	GeefLeefloonbedragen	gedeeld	nee
`loopbaanARZA`	GeefLoopbaanARZA	gedeeld	nee
`mobility`	Mobiliteit	REST API	ja
`personalIncomeTax`	GeefAanslagbiljetPersonenbelasting	gedeeld	nee
`poc`	Kadaster	specifiek	ja
`registreerbewijs`	RegistreerBewijs	gedeeld	nee
`ri`	Repertorium	specifiek	nee
`sme`	GeefJaarrekeningen	specifiek	nee
`sociaalstatuut`	GeefSociaalStatuut	gedeeld	nee
`werkrelaties`	GeefWerkrelaties	gedeeld	nee
`zoekeigendomstoestanden`	ZoekEigendomstoestanden	specifiek	nee
`zoekpersoonopadres`	ZoekPersoonOpAdres	gedeeld	nee
`zorgtoeslag`	GeefZorgToeslag	gedeeld	nee

SSL-instellingen

Specifiek

Vervang de placeholder {service} door de specifieke service die je wil implementeren.

Voorbeelden:

aws.zoekeigendomstoestanden.client.ssl.trust-store-path
aws.ri.client.ssl.trust-store-path
aws.poc.client.ssl.trust-store-path
aws.mobility.client.ssl.trust-store-path

Eigenschap	Default	Beschrijving
`aws.{service}.client.ssl.trust-store-path`	-	Pad naar het truststore‑certificaat (AWS Secrets Manager‑pad of lokaal bestand).
`aws.{service}.client.ssl.private-key-path`	-	Pad naar de private key (AWS Secrets Manager‑pad of lokaal bestand).
`aws.{service}.client.ssl.private-key-password-path`	-	Pad naar het wachtwoord van de private key (AWS Secrets Manager‑pad of lokaal bestand).
`aws.{service}.client.ssl.keystore-jks`	-	Lokaal bestandspad voor de gegenereerde PKCS12‑keystore (wordt tijdens runtime aangemaakt).
`aws.{service}.client.ssl.trustore-jks`	-	Lokaal bestandspad voor de truststore (JKS).
`aws.{service}.client.ssl.security`	`sign`	Beveiligingsmodus: `sign` (XML‑ondertekening) of `esb` (basic auth via ESB).`
`aws.{service}.client.ssl.username`	`admin`	Gebruikersnaam voor ESB basic authentication.
`aws.{service}.client.ssl.password`	`admin`	Wachtwoord voor ESB basic authentication.
`aws.{service}.client.ssl.use-mocks`	`false`	`Indien \`true`, worden requests naar het MAGDA mock‑endpoint gestuurd en worden security‑headers overgeslagen.`
`aws.{service}.client.ssl.kong-api-key`	-	`Kong API Gateway key (wordt toegevoegd als \`x-apikey` HTTP‑header indien ingesteld). Enkel voor GHP (GeefHistoriekPersoon)

Gedeeld

Eigenschap	Default	Beschrijving
`aws.default.client.ssl.trustore-jks`	`default-trust-store.jks`	Pad naar het lokale TrustStore-bestand (JKS) dat vertrouwde certificaten bevat voor SSL-verificatie.
`aws.default.client.ssl.keystore-jks`	`default-key-store.jks`	Pad naar het lokale KeyStore‑bestand (JKS/PKCS12) met de clientcertificaten voor mTLS.
`aws.default.client.ssl.trust-store-path`	`default/prod/2ssl/certificate`	Pad (bv. AWS Secrets Manager of SSM) naar het certificaat dat in het TrustStore wordt geplaatst.
`aws.default.client.ssl.private-key-path`	`default/prod/2ssl/private-key`	Pad (bv. AWS Secrets Manager of SSM) naar de private key die voor mTLS gebruikt wordt.
`aws.default.client.ssl.private-key-password-path`	`default/prod/2ssl/private-key-password`	Pad (bv. AWS Secrets Manager of SSM) naar het wachtwoord van de private key.

Service url instellingen

Dit is een verplichte instelling voor elke service die je wil aanspreken. Vervang {service} door de specifieke service in kwestie.

Eigenschap	Default	Beschrijving
`skryv.connectors.magda.{service}.service-url`	-	Dit is een verplichte instelling voor elke service die je wil aanspreken.

Voorbeelden:

skryv.connectors.magda.ebox.service-url
skryv.connectors.magda.gp.service-url
skryv.connectors.magda.zoekeigendomstoestanden.service-url
skryv.connectors.magda.zorgtoeslag.service-url

Service specifiek

Toegespitst op de service die je wil gebruiken, voeg je eventueel 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.