Profiel Service

De Profiel Service stelt burgers en ondernemers in staat om op één vertrouwde plek hun contactgegevens en communicatievoorkeuren te beheren, en biedt overheidsinstanties via federatieve koppelingen veilige, actuele en herbruikbare profielinformatie voor persoonlijke en efficiënte dienstverlening.

Documentatie over de Profiel Service is te vinden op de documentatie website van MijnOverheidZakelijk.

Status

Levenscyclus: development (zie publiccode.yml). De service draait in een POC-omgeving en wordt voorbereid op landing op de Logius Private Cloud (LPC).

API

• Base path: /api/profielservice/v1
• OpenAPI spec: /openapi.json
• Swagger UI: /docs
• Health en metrics: op aparte management-port 9090 onder /q/health en /q/metrics (niet via de publieke port).

De API volgt de NL GOV API Design Rules 2.1.0. Foutmeldingen volgen RFC 9457 (application/problem+json).

Contract-first

Het contract in src/main/resources/META-INF/openapi.yaml is de bron. Annotatie-scanning staat uit (mp.openapi.scan.disable=true), dus datzelfde bestand wordt statisch op /openapi.json geserveerd én voedt de codegen: openapi-generator-maven-plugin maakt er tijdens generate-sources de request- en response-DTO's uit, in nl.rijksoverheid.moz.api.generated.model.

Praktisch betekent dat: schrijf geen DTO met de hand en bewerk niets onder target/generated-sources — pas het contract aan en draai de build opnieuw. De controllers zijn wél handgeschreven (generateApis=false, zie de toelichting in pom.xml); RouteDekkingTest bewaakt dat ze paden en methodes van het contract blijven volgen.

Lokaal draaien

Vereisten:

• Java 25
• Maven (of de meegeleverde wrapper ./mvnw)
• PostgreSQL voor quarkus:dev (zie docker-compose.yml); de tests starten hun eigen embedded PostgreSQL

# Database opstarten (zie docker-compose.yml)
docker compose up -d

# Dev-modus (live reload, http://localhost:8080)
./mvnw quarkus:dev

# Tests (starten zelf een embedded PostgreSQL, geen Docker nodig)
./mvnw verify

Configuratie

Lokale ontwikkel-secrets horen in een gitignored src/main/resources/application-dev.properties:

• notifynl.emailverificatie.api-key, template-id, reference — van https://admin.notifynl.nl/, vraag het team voor toegang.
• quarkus.datasource.* — alleen nodig als je geen docker compose gebruikt.

Productie-configuratie staat in de deployment-repo.

hash.pepper

HashHelper pseudonimiseert identificatienummers (BSN/KVK/RSIN) tot het subject-id in het Logboek Dataverwerkingen met een keyed HMAC-SHA-256. De sleutel komt uit hash.pepper; zonder die sleutel is een hash over een BSN triviaal terug te rekenen.

application.properties bevat een dev/test-placeholder. Prod en acc krijgen een eigen geheime waarde uit het secret; de lege %prod/%acc-override staat in de deployment-repo, dus daar start de applicatie niet op zonder waarde. Deze repo zet die override niet, dus een ZAD-preview zonder HASH_PEPPER valt terug op de placeholder hierboven in plaats van te falen. Zie docs/zad-deploy.md.

Het pseudoniem is stabiel zolang de pepper gelijk blijft. Bij het roteren van de pepper krijgen alle subjecten een nieuw pseudoniem en correleren oude logboekregels niet meer met nieuwe.

Quarkus

Dit project draait op Quarkus. Meer informatie hierover staat in quarkus.md.

Circuit breaker voor de Verificatie-service API

Bij herhaalde fouten in de communicatie met de externe verificatie-service (bijvoorbeeld door netwerkproblemen of uitval) wordt de circuit breaker actief. Na een configureerbaar aantal mislukte aanroepen gaat het circuit open: nieuwe verzoeken worden direct afgewezen zonder dat er opnieuw een verbinding wordt geprobeerd. Dit voorkomt dat de applicatie vastloopt op trage of niet-reagerende externe diensten. Na een wachttijd gaat het circuit in half-open toestand en worden nieuwe aanroepen opnieuw toegestaan om te testen of de externe dienst hersteld is.

De circuit breaker is gedeeld tussen de twee aanroepen naar de verificatie-service (requestEmailVerificationCode en verifieerEmail). Dit betekent dat herhaalde fouten op het ene endpoint ook het andere endpoint beschermen: als de verificatie-service voor de ene aanroep niet bereikbaar is, is dat hoogstwaarschijnlijk voor de andere ook het geval. De gedeelde circuit breaker wordt beheerd via VerificatieServiceGuard.

Circuit breaker instellingen

De circuit breaker wordt geconfigureerd via de volgende properties in application.properties. De waarden in de code gelden als standaardwaarden en kunnen per omgeving worden overschreven.

• verificatie-service.circuit-breaker.request-volume-threshold: Minimum aantal aanroepen binnen het meetvenster voordat het circuit kan openen (standaard 5).
• verificatie-service.circuit-breaker.failure-ratio: Drempelwaarde voor het percentage mislukte aanroepen waarboven het circuit opent (standaard 1.0 — circuit opent alleen bij volledige uitval).
• verificatie-service.circuit-breaker.delay: Wachttijd in seconden in de open toestand voordat het circuit half-open gaat (standaard 30).
• verificatie-service.circuit-breaker.success-threshold: Aantal opeenvolgende successen in half-open toestand dat nodig is om het circuit te sluiten (standaard 2).

Contracttesting

De Profiel Service maakt gebruik van contracttesting om te waarborgen dat wijzigingen aan de API consumenten niet ongemerkt breken.

Hoe het werkt

• OpenAPI-schemavalidatie: elke integratietest valideert automatisch dat verzoeken en antwoorden overeenkomen met de OpenAPI-specificatie die de draaiende service publiceert (/openapi.json).
• Pact-providerverificatie: pact-bestanden (JSON) in src/test/resources/pacts/ beschrijven de verwachte contracten. De provider test verifieert dat de service hieraan voldoet. Het huidige bestand moza-profiel-service.json is een zelftestcontract van de provider zelf.

Contracten bijdragen als consument

Ben je consument van de Profiel Service API en wil je een contract bijdragen? Neem dan contact op met het team om dit samen te bespreken. We stellen dan samen een pact-bestand op dat de verwachtingen van jouw toepassing beschrijft.

Een Pact Broker is een mogelijke toekomstige stap, afhankelijk van de behoefte van het team.