Status	Conceptversie
Laatste update	21-11-2025
Auteur	Robin Alderliesten

Visie

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.

Wat is de Profiel Service

De Profiel Service vormt een bouwsteen binnen de digitale overheid. Het biedt burgers én ondernemers één centrale plek waar zij hun contactgegevens en communicatievoorkeuren kunnen beheren. Overheidsorganisaties kunnen deze gegevens via gestandaardiseerde API’s opvragen en gebruiken om betrouwbaar, persoonlijk en efficiënt te communiceren — altijd met toestemming van de gebruiker.

Waar vandaag de dag veel contactgegevens versnipperd zijn opgeslagen in losse portalen en applicaties, brengt de Profiel Service dit samen in een centraal, goed beheerd register. Daarmee vormt het een solide basis voor federatieve dienstverlening: één betrouwbare bron die andere federatieve services ondersteunt met actuele en verifieerbare profielinformatie.

Waarom een Profiel Service

Voor burgers bestaat al de mogelijkheid om bepaalde gegevens te beheren via MijnOverheid, maar ondernemers vallen grotendeels buiten de boot. Zij moeten hun contactinformatie nog te vaak handmatig herhalen bij elke overheidsdienst. Ook is er geen centrale plek waar communicatievoorkeuren kunnen worden vastgelegd — zoals de voorkeur voor digitaal of post.

De Profiel Service lost dit op door:

• één betrouwbare bron van contact- en voorkeursgegevens te bieden,
• overheidsbreed hergebruik mogelijk te maken,
• burgers en ondernemers de regie te geven over hoe zij met de overheid communiceren.

Doel en waarde

De Profiel Service is bedoeld om:

• Burgers en ondernemers controle te geven over hun profielgegevens en communicatievoorkeuren, op één vertrouwde plek.
• Overheidsorganisaties te voorzien van actuele en verifieerbare gegevens, rechtstreeks uit een centrale bron.
• De digitale overheid te versterken met een herbruikbare bouwsteen die past binnen de Generieke Digitale Infrastructuur (GDI).

Functionele doelstellingen

• Beheer van profielgegevens: e-mailadres, telefoonnummer, postadres etc. op een centrale plek
• Instellen van contactvoorkeuren: bijvoorbeeld voorkeur voor digitaal of post, notificatiekanalen, etc.
• Instellen van overige voorkeuren; denk aan weergaveinstellingen en overige sets van voorkeuren
• Ondersteuning van meerdere authenticatiemiddelen: DigiD, eHerkenning, eIDAS
• Koppeling met registers: KVK, BRP, BAG, gegevens bij de bron opvragen
• Federatief delen: gegevens worden centraal opgeslagen en beschikbaar gesteld aan verifieerbare dienstverleners

Strategische doelstellingen

• Versterken van vertrouwen in digitale dienstverlening (conform de Generieke Digitale Infrastructuur (GDI))
• Verlagen van administratieve lasten voor ondernemers
• Verbeteren van “omnichannel communicatie” tussen overheid en gebruiker
• Herbruikbaarheid van profieldata over meerdere overheidsdomeinen heen
• Incrementele groei: klein beginnen en iteratief uitbreiden

Benodigde afspraken

Om een centrale Profiel Service voor burgers en ondernemers neer te zetten is het noodzakelijk dat dienstverleners deze adopteren in hun eigen ecosystemen en MijnOmgevingen. Hiervoor werken we volgens de principes van het programma Generieke Digitale Infrastructuur (GDI). Dit betekent dat afspraken en standaarden worden neergezet en de Profiel Service als voorziening beschikbaar wordt gemaakt.

In de komende periode werken we aan het verzamelen van informatie en het beantwoorden van vragen die hierover onstaan bij de uitwerking.

Gefaseerde ontwikkelstrategie

De Profiel Service wordt stapsgewijs gerealiseerd, met een nadruk op eenvoud, hergebruik en federatieve samenwerking.

Architectuur en uitgangspunten

• Centraal profielregister: één betrouwbare bron van waarheid voor contact- en voorkeursgegevens.
• Ondersteuning voor federatieve diensten: de Profiel Service zelf is centraal, maar stelt gegevens beschikbaar aan federatieve toepassingen.
• NeRDS: Ontwikkeling volgt Nederlandse Richtlijn Digitale Systemen (NeRDS).
• Open standaarden: API’s volgen NORA, NL GOV API Design Rules en GDI-richtlijnen.
• Federatieve identiteit: toegang via DigiD, eHerkenning en eIDAS.
• Privacy by design: minimale dataverwerking, transparantie en logging conform LDV.
• Data bij de bron: de Profiel Service als basisregister voor contactvoorkeuren

Lange termijn visie

Op langere termijn groeit de Profiel Service uit tot een generieke bouwsteen binnen de GDI — een betrouwbare voorziening waarop iedere overheidsorganisatie kan aansluiten.

• Burgers en ondernemers hebben volledige regie over hun gegevens.
• Overheidsorganisaties communiceren veilig en consistent met hun gebruikers.
• De Profiel Service ondersteunt een breed palet aan diensten, zoals:
  • MijnOverheid
  • MijnServices (VNG)
  • Digitaal Ondernemersplein
  • Notificatie- en berichtenservices (NotifyNL, BBO)
  • Alle MijnOmgevingen van overheidsdienstverleners.

Positionering voor stakeholders

Oproep tot samenwerking

De ontwikkeling van de Profiel Service vraagt samenwerking tussen beleidsmakers, ontwerpers, ontwikkelaars en uitvoeringsorganisaties.
Alleen door gezamenlijk standaarden te ontwikkelen, adoptie te stimuleren en kennis te delen ontstaat een breed gedragen voorziening die écht waarde toevoegt.

Wij nodigen daarom alle overheidsorganisaties uit om mee te denken, mee te bouwen en mee te leren.
Samen maken we van de Profiel Service niet alleen een technische voorziening, maar een fundament voor betrouwbare, toegankelijke en toekomstbestendige digitale dienstverlening.

Documentatie & Bronnen

• MijnOverheid Zakelijk startpagina - Meer informatie en documentatie over het programma MijnOverheid Zakelijk is te vinden via onze startpagina.
• Profiel Service op GitHub - Onze oplossingen worden Open Source ontwikkeld en zijn te vinden op de Github van MinBZK

Profiel Service

Context

Er bestaan al voorzieningen waarmee burgers gegevens kunnen beheren (zoals de MijnOverheid-instellingen), maar ondernemers vallen daar grotendeels buiten. Bovendien is de huidige inrichting vaak monolithisch en niet federatief; data wordt decentraal en niet herbruikbaar opgeslagen bij de dienstverleners.

Een aantal uitdagingen

• Ondernemers moeten vaak opnieuw hun gegevens invullen bij elke overheidsdienst
• Er is géén centrale plek waar contactgegevens en -voorkeuren beheerd of opgehaald kunnen worden
• Er is onvoldoende inzicht over wie toegang heeft tot welke gegevens
• Met name voor ondernemers zijn er nog geen voorzieningen beschikbaar en komen er ook niet binnenkort

Doel

Burgers en ondernemers kunnen op één vertrouwde plek hun communicatievoorkeuren en contactgegevens opslaan.

Overheidsorganisaties kunnen bij deze centrale service actuele en betrouwbare contactvoorkeuren en contactgegevens ophalen, o.a. voor het versturen van notificaties.

De Profiel Service is een centraal register dat gebruikt kan worden in portalen of andere interactiecomponenten voor het ophalen van de voorkeuren van burgers en ondernemers.

De Profiel Service bevat persoons- en bedrijfsgegevens en die gebruikt kunnen worden voor de communicatie tussen de gebruiker en overheidsorganisaties. Dit zijn zowel contactgegevens (zoals e-mailadres en telefoonnummer) als voorkeuren waarover de communicatie tussen de gebruiker en de overheidsorganisatie plaatsvindt.

Functioneel overzicht

Inleiding

Dit hoofdstuk bouwt voort op de context en visie en verwijst naar aanvullende documentatie en diagrammen. Het biedt kort en duidelijk inzicht in wat de Profiel Service doet, voor wie het dat doet en hoe de belangrijkste informatiestromen lopen.

Overzicht

De Profiel Service biedt één centrale voorziening waar burgers en ondernemers hun contactgegevens en communicatievoorkeuren kunnen beheren, en waar overheidsorganisaties deze, met toestemming en volgens afspraken, betrouwbaar kunnen opvragen. Daarmee ondersteunt de Profiel Service federatieve en herbruikbare digitale dienstverlening binnen de overheid.

Wat het systeem feitelijk doet, is het centraal opslaan en ontsluiten van profielgegeven/contactgegevens, voor burgers en ondernemers. Belangrijke gebruikers en hun behoeften zijn:

• Burger/ondernemer: eigen profiel beheren (inzien, toevoegen, wijzigen, verwijderen), voorkeuren instellen en waar nodig gegevens verifiëren.
• Dienstverlener/Vakapplicatie: via API’s profiel- en contactgegevens ophalen.

Belangrijke leveranciers zijn:

• Identiteitsproviders (DigiD, eHerkenning, eIDas): verzorgen de authenticatie waarmee toegang tot het profiel mogelijk is.
• De KvK, integratie met KvK voor verrijking en verificatie van data bij de bron waaronder api gebruik om identificaties (BSN & KvK) aan elkaar te koppelen.
• Digitaal Ondernemersplein die noodzakelijk gaat zijn in het bijhouden van actuele updates over bijvoorbeeld subsidies of wetswijzigingen.

Kernfunctionaliteiten in het kort:

• Profiel inzien met overzicht van contactgegevens (e-mail, telefoon, postadres) en communicatievoorkeuren (bijv. kanaalvoorkeur, taal).
• Profiel beheren: toevoegen, wijzigen en verwijderen van contactgegevens; instellen van voorkeuren (algemeen en dienstspecifiek/scope-gebaseerd); verifiëren van contactkanalen (bijv. via bevestigingsmail/sms; status vastleggen).
• Profiel ophalen door dienstverleners: actuele contactgegevens en voorkeuren opvragen op basis van een partij-identificatie (bijv. KVK, BSN, RSIN), inclusief scope voor dienst/dienstverlener; inclusief verifieerbaarheidsindicatoren ontvangen.
• Identificaties koppelen en beheren: vastleggen van BSN/KvK/RSIN/etc. en koppelen aan één partijprofiel.
• Toegang verlenen aan dienstverleners conform afsprakenstelsel en autorisaties van het Federatieve Data Stelsel (FDS).
• Logging en transparantie (conform LDV): registreren van relevante gebeurtenissen ten behoeve van inzage en troubleshooting.
• Audit logging voor juridische doeleinde.

Belangrijkste processen en informatiestromen:

1. Authenticatie en sessieopbouw – Inloggen via DigiD (burger/zzp’er), eHerkenning (ondernemer) of eIDas (buitenlandse belanghebbende); autorisatie en scoping bepalen welk profiel en welke gegevens zichtbaar/bewerkbaar zijn. Flow verder uitgewerkt in 07-code-Aurthenticatie.

In deze flowchart is te zien hoe de diverse inlogopties worden gebruikt en welke identificerende informatie wij dan aan de gebruiker kunnen koppelen.

flowchart TD;
    %% Trigger
        TRIGGER([De ondernemer wilt zijn contactgegevens updaten])-->S1;

    %% DigId scenario
        S1[Het systeem laat de inlog opties zien: 1. Digid, 2. eHerkenning, 3. eIDas als Burger 4. eIDas als Organisatie]-->S2;
        S2[De ondernemer kiest Digid]-->S3;
        S3[Het systeem met behulp van het BSN haalt hij de relevant KVK's op bij de KVK-BSN api.];
        S3-->SUCCESS_DigId;

    %% eHerkenning scenario
        S1-->EXT2a1;
        EXT2a1[De ondernemer kiest eHerkenning]-->EXT2a2;
        EXT2a2[Het systeem haalt de KVK & BSN uit de eHerkenning. Voor BSN komt die uit NIN & NIN_TYPE.]-->EXT2a3;
        EXT2a3[OPTIE: Het systeem gebruikt het BSN om de andere KVK's op te halen bij de KVK-BSN api??.];
        EXT2a2-->SUCCESS_eHerkenning;
        EXT2a3-->SUCCESS_eHerkenning;

    %% eIDas scenario
        S1-->EXT3a1;
        EXT3a1[De ondernemer kiest eIDas Burger]-->EXT3a2;
        EXT3a2[Het systeem haalt de Person Identifier, en optioneel Representative Person Identifier uit eIDas.];
        EXT3a2-->SUCCESS_eIDas_Burger;

        S1-->EXT4a1;
        EXT4a1[De ondernemer kiest eIDas Organisatie]-->EXT4a2;
        EXT4a2[Het systeem haalt de Legal Person Identifier, en optioneel Legal Entity Identifier uit eIDas.];
        EXT4a2-->SUCCESS_eIDas_Organisatie;

        SUCCESS_DigId([De ondernemer kan zijn contactgegevens updaten voor zichzelf en al zijn ondernemingen]);
        SUCCESS_eHerkenning([De ondernemer kan zijn contactgegevens updaten voor zichzelf en 1 onderneming]);
        SUCCESS_eIDas_Burger([De ondernemer kan zijn contactgegevens updaten voor deze eIDas Person Identifier]);
        SUCCESS_eIDas_Organisatie([De ondernemer kan zijn contactgegevens updaten voor deze eIDas Legal Person Identifier]);

2. Profiel inzien en beheren – Gebruiker bekijkt bestaande gegevens en voorkeuren en voert wijzigingen door. Zie sequentie diagrammen hierover in 07-code-ProfielBeheren en 08-data-sequentiediagrammen.

In de onderstaande sequentiediagram is te zien hoe een gebruiker zijn profiel kan bekijken en bijwerken als hij inlogd met DigiD.

sequenceDiagram
    actor Ondernemer
    participant MOZa as MOZa Portaal
    participant KvK as KvK
    participant Profiel as Profiel Service

    Ondernemer->>MOZa: Logt in
    activate MOZa

    alt Als login via DigiD
        MOZa->>KvK: Haal ondernemingen op voor BSN
        deactivate MOZa
        activate KvK
        KvK-->>MOZa: Geeft ondernemingen terug (KvK-nummers)
        deactivate KvK
        activate MOZa
    end

    MOZa->>Ondernemer: Toon Profiel Pagina
    Ondernemer->>MOZa: Opent pagina 'Contactvoorkeuren'

    MOZa->>Profiel: GET contactvoorkeuren (BSN + KvK)
    deactivate MOZa
    activate Profiel
    Profiel-->>MOZa: Contactvoorkeuren terug
    deactivate Profiel
    activate MOZa

    MOZa->>Ondernemer: Toon pagina 'Contactvoorkeuren'

    Ondernemer->>MOZa: Past contactvoorkeur aan

    MOZa->>Profiel: PATCH contactvoorkeur (BSN + KvK)
    deactivate MOZa
    activate Profiel
    Profiel-->>MOZa: Ok (voorkeur bijgewerkt)
    deactivate Profiel
    activate MOZa

    MOZa-->>Ondernemer: Toont bevestiging
    deactivate MOZa

3. Profiel bevragen door dienstverlener – Vakapplicaties (of OMC/dergelijks) halen via API contactgegevens/voorkeuren op. Scoping per dienst/dienstverlener bied focus en ondersteunt dataminimalisatie. Zie 08-data-sequentiediagrammen.

Hier is te zien is een eenvoudige sequentie diagram hoe de dienstverlener de informatie zou ophalen, en bijvoorbeeld gebruikt op een persoon aan de hand daarvan een notificatie te versturen.

sequenceDiagram
  participant Dienstverlener@{"type" : "collections"}
  participant PS as Profiel Service
  participant NS as Notificatie Service
  actor BO as Burger of Ondernemer

  Dienstverlener ->> PS: Stuurt identificatienummer
  PS -->> Dienstverlener: Levert contactvoorkeuren
  Dienstverlener ->> NS: Stuurt inhoud notificatiebericht + voorkeurskanaal
  NS ->> BO: Stuurt bericht via voorkeurskanaal
  NS -->> Dienstverlener: Status aflevering (OK/NOK)

Inleiding

Dit hoofdstuk vat de belangrijkste niet-functionele eisen (kwaliteitseisen) voor de Profiel Service samen. De eisen zijn zo veel mogelijk SMART geformuleerd en sluiten aan op het functioneel overzicht en de context. Waar relevant verwijzen we naar architectuurkeuzes in de ADR’s en ondersteunende documentatie.

Overzicht

De onderstaande kwaliteitseisen zijn architectonisch significant en sturen ontwerp- en implementatiekeuzes:

• Beveiliging & Privacy (AVG, authenticatie/authorisatie, dataminimalisatie)
• Beschikbaarheid & Continuïteit
• Performance & Schaalbaarheid
• Auditability & Logging (LDV)
• Interoperabiliteit & Open Standaarden
• Observeerbaarheid (monitoring, metrics, tracing)
• Herstelbaarheid (back-up/restore, DR)

Waar zaken bewust buiten scope vallen, is dit expliciet benoemd.

Beveiliging & Privacy

• Authenticatie: Via erkende federatieve identiteiten (DigiD, eHerkenning, eIDas) conform ADR 0006. Eisen: OIDC/OAuth 2.0 flows, tokens met beperkte scopes, token TTL ≤ 60 min; refresh alleen server-to-server waar passend. Meetbaar via IDP-config en token policies.
• Autorisatie: scope-gebaseerd mogelijkheid (per dienst/dienstverlener) met dataminimalisatie. Alleen de minimaal opgevraagde attributen worden geleverd. Verplicht ‘least privilege’ op API-niveau & ontsloten via het FDS.
• Privacy/AVG: verwerkingsregister en grondslagregistratie op orde, volgens AVG artikel 6 en 30 respectief. Daarbij komt mee alleen noodzakelijke persoonsgegevens opslaan.
• Dataretentie: operationele logs max. 90 dagen, audit-logs conform bewaartermijn in ADR 0005/0007. DPIA uitgevoerd vóór productie.
• Transport & opslag: TLS 1.2+ in transit; gevoelige secrets via sealed secrets, geen gevoelige data in logs. Encryptie-at-rest verplicht indien toepasbaar.

Beschikbaarheid & Continuïteit

Er is nog geen baseline voor bedacht, maar denk hier aan bijvoorbeeld:

• Doel beschikbaarheid betafase: ≥ 50% tijdens kantoortijden. Doel productie: ≥ 99,9% 24x7 (excl. gepland onderhoud). Vastgelegd als Service Level Objective (SLO) en gemonitord.
• Onderhoud: onaangekondigd tijdens betafase.

Performance & Schaalbaarheid

Er is nog geen baseline voor bedacht, maar denk hier aan bijvoorbeeld:

• Lezen (profiel opvragen door dienstverlener of gebruiker): p95 latency ≤ 150 ms binnen hetzelfde datacentrum; p99 ≤ 300 ms.
• Schrijven (profiel wijzigen door gebruiker): p95 end-to-end ≤ 500 ms exclusief out-of-band kanaalverificatie (e-mail/SMS). Kanaalverificatie is async en beïnvloedt UI-flow, niet server-SLA.
• Capaciteit: initieel kleine groep profielen (beta), maar schaalbaar naar 2M+ profielen. Opslag en indices ontwerpen voor lineaire schaal.

Auditability & Logging (LDV)

• Audit log: conform ADR 0005 en ADR 0007 worden relevante mutaties en bevragingen vastgelegd met wie/wat/wanneer/waarom. Alle muterende acties audit-logged en elke bevragingen geregistreerd voor transparantie/terugzoekbaarheid volgens LDV standaard.
• Onweerlegbaarheid: timestamps (UTC), correlatie-ID, en event-idempotency waar relevant. Toegang tot audit-logs is strikt geautoriseerd.

Interoperabiliteit & Open Standaarden

• API-contracten in OpenAPI 3.0+, JSON over HTTPS. HTTP-standaarden volgen REST best practices.
• Identiteiten en claims volgen de OIDC-standaard; authenticatie verloopt via erkende IdP’s (DigiD, eHerkenning, eIDAS).
• Koppelingen met KvK en andere bronnen via hun officiële API-standaarden. Afstemming met Federatief Data Stelsel (FDS) en LDV-implementatie (ADR 0010).

Observeerbaarheid

Er is nog geen baseline voor bedacht, maar denk hier aan bijvoorbeeld:

• Metrics: minimaal request-latency (p50/p95/p99), error-rate per endpoint, throughput, resource verbruik. Dashboards gepubliceerd en gedeeld met beheer.
• Tracing: Gedistribueerd tracing over inkomende en uitgaande calls. Log-niveau: INFO standaard, WARN/ERROR voor afwijkingen.

Herstelbaarheid (Back-up/Restore, DR)

Er is nog geen baseline voor bedacht, maar denk hier aan bijvoorbeeld:

• RPO ≤ XYZ minuten
• RTO ≤ 1? dag in pilot, ≤ XYZ minuten in productie.
• Back-ups getest op herstel per half jaar.
• Audit-log reconstructie (reverse delta read) is niet standaard, maar beschikbaar als laatste redmiddel bij noodgevallen (zie ADR 0005).

Buiten scope / expliciete uitsluitingen

• Meertalige UI is niet vereist in de betafase?. ZIE PUNT 2 TOEGANKELIJKHEID & GEBRUIKSVRIENDELIJKHEID.
• SEO en PWA-eisen zijn momenteel niet van toepassing.
• Offline-first gebruik is uitgesloten.

Meting en borging

• Geautomatiseerde kwaliteitscontroles (linting, security scanning/CVE), contracttests op API’s, Lighthouse voor front-end, performance tests (load/stress) in CI/CD, Unit tests voor business logica.
• SLO’s/SLA’s worden actief gemonitord en afwijkingen leiden tot incidenten en/of verbeteracties.

Beperkingen

Inleiding

Deze sectie beschrijft de expliciete randvoorwaarden en beperkingen waarbinnen de Profiel Service wordt ontworpen en gerealiseerd. Doel is om gemaakte keuzes en context te borgen en later te kunnen herleiden waarom bepaalde opties zijn overwogen.

Overzicht

De volgende categorieën beperkingen zijn van toepassing. Per punt noemen we wat de beperking inhoudt, door wie/waarom deze is opgelegd en de impact op de architectuur.

Organisatorische en tijd/budget beperkingen

• Betafase: lever een werkende beta met kernfunctionaliteit binnen beperkte tijd en middelen. Opgelegd door programma. Impact: focus op ‘must haves’; nice-to-haves. Systeem is uitbreidbaar richting productie, maar implementeert in de beta een minimale set.

Identiteit, authenticatie en autorisatie

• Verplicht ondersteuning van federatieve authenticatie (DigiD, eHerkenning, eIDas) en OIDC/OAuth2 (ADR 0006). Opgelegd door rijksbeleid en interoperabiliteitseisen en benodigde gebruikersinformatie. Impact: eigen credential management is uitgesloten; integratie met IDP’s bepaalt login-flows en token-handling. Voor betafase waarschijnlijk alleen eHerkenning.
• Scope-gebaseerde autorisatie voor dienstverleners via FDS; scopes beperken toegang tot de minimaal noodzakelijke rechten (least privilege), bijvoorbeeld read-only waar van toepassing. Opgelegd door architectuurkader; alle API’s moeten scopes/claims afdwingen.

Juridisch en compliance

• AVG toepasselijke logging/LDV-vereisten (ADR 0007, 0010). Opgelegd door wet- en regelgeving. Impact: auditeerbare gebeurtenissen, transparantie en bewaartermijnen zijn verplicht, persoonlijk identificeerbare informatie in logging vermijden.
• Gebruik van KvK-gegevens conform betreffende API-voorwaarden. Impact: caching/bewaren van externe gegevens is ingezet, met beperkingen, en aan voorwaarden gebonden.

Technologiestack en standaarden

• API’s in OpenAPI 3.0+, JSON over HTTPS; gebruik van standaard HTTP-protocollen. Impact: geen propriëtaire protocol keuzes.

Integraties en afhankelijkheden

• Afhankelijkheid van externe stelsels/voorzieningen: IDP’s (DigiD/eHerkenning/eIDas), KvK, LDV/FDS. Opgelegd door functionele doelstellingen. Impact: beschikbaarheid en performance worden mede bepaald door externe SLA’s; timeouts, retries en circuit breakers zijn nodig. TODO Willen wij hiervoor circuit breakers gebruiken?

Deploy- en hostingkader

• Uitrol op een standaard overheidscloud/infrastructuur met centrale voorzieningen (logging, monitoring, secret management). Opgelegd door hostingpartij/beheer. Impact: keuze voor specifieke PaaS-diensten of databases kan beperkt zijn; encryptie-at-rest en netwerkpolicies volgen platform-standaard.
• Netwerkbeperkingen: alleen uitgaand verkeer naar whitelisted endpoints (bijv. KvK, IDP’s). Impact: service discovery en integraties moeten binnen deze restricties werken.

Ontwikkelproces en team

• Uitgebreid team, maar gedeelde capaciteit met andere deelprojecten. Opgelegd door programma. Impact: prioritering op kerndoelen, gefaseerde oplevering. Automatisering (CI/CD, tests) is essentieel om snelheid/kwaliteit te borgen.

Data en migratie

• Geen migratie van historisch profielmateriaal uit legacy. Opgelegd door scopebeperking. Impact: betafase start ‘greenfield’; koppeling aan bestaande datasets gebeurt via bronverificatie (b.v. KvK). Potentiële datamigratie naar productie wordt onderzocht in overleg met de betrokken dienstverleners, om te bepalen of deze technisch haalbaar is en of het meerwaarde biedt.

Waarom deze beperkingen ertoe doen

• Beperken van keuzes versnelt ontwerp en implementatie, maar stuurt ook de architectuur: federatieve auth en FDS-scopes vereisen strikte scheiding van verantwoordelijkheden en dataminimalisatie; LDV/AVG dwingt auditability en logging-architectuur; hosting- en netwerkstandaarden bepalen integratiepatronen (API-gateway, TLS, secrets). Door deze constraints expliciet te maken, voorkomen we schijnbaar ‘vreemde’ keuzes achteraf.

Verwijzingen

• ADR 0005 – AuditLog & EventSourcing
• ADR 0006 – Federatieve authenticatie en autorisatie op basis van OIDC en eIDas
• ADR 0007 – Logboek dataverwerking (LDV)
• ADR 0009 – NL Design System
• ADR 0010 – LDV implementatie

Design Principes

Inleiding

Het doel van dit hoofdstuk is om expliciet te maken welke principes we volgen, zodat ontwerp- en implementatiekeuzes consistent en uitlegbaar zijn voor alle betrokkenen. Indien een principe is vastgelegd in een ADR of elders, is een verwijzing opgenomen. In andere gevallen is een korte toelichting toegevoegd.

Principes

De onderstaande principes ondersteunen de kwaliteitseisen in het kwaliteitseisen hoofdstuk en vormen samen met de ADR’s de basis voor ontwerpkeuzes in de software-architectuur.

• Open standaarden, tenzij
  We geven de voorkeur aan open, breed gedragen standaarden voor interoperabiliteit.
  Voorbeelden: OpenAPI 3 voor API’s, JSON/HTTP, OIDC/OAuth 2.0 voor federatieve login.

• Contract-first API-ontwikkeling (OpenAPI)
  API’s worden beschreven in OpenAPI en versiebeheer (semantic versioning) wordt toegepast op contracten. Documentatie en try-out via Swagger.

• Beveiliging en privacy by design
  Minimaalheidsprincipe (data-minimalisatie), least-privilege, encryptie in transit, auditing van mutaties en bevragingen.
  Verwijzingen: ADR 0005 (AuditLog/EventSourcing), ADR 0006 (federatieve authenticatie/authorisatie), ADR 0007 (Logboek Dataverwerking), ADR 0008 (Data-eigenaar).

• Federatieve authenticatie en autorisatie
  Inloggen via erkende identiteiten (DigiD, eHerkenning, eIDas). Token-gebaseerde toegang via OIDC/OAuth 2.0.
  Verwijzing: ADR 0006.

• Hoge cohesie, lage koppeling
  Services en modules hebben een duidelijke, beperkte verantwoordelijkheid en communiceren via expliciete contracten. Dit vergroot onderhoudbaarheid en vervangbaarheid.

• SOLID en DRY
  Klassen en componenten volgen Single Responsibility; we vermijden duplicatie en prefereren hergebruik van gedeelde bouwblokken.

• Dependency Injection
  Losse koppeling via interfaces en dependency inversion; concrete implementaties worden via CDI geïnjecteerd.
  Het gekozen DI-mechanisme volgt de Quarkus-standaard (Jakarta CDI/Arc).

• Architecturale gelaagdheid en scheiding van verantwoordelijkheden
  Duidelijke scheiding tussen API-/controllerlaag, applicatie-/servicelaag en persistentierepository.
  Businesslogica bevindt zich uitsluitend in de servicelaag; controllers bevatten geen businesslogica en hebben geen directe database-toegang.

• Stateless services
  Schaalbaarheid en eenvoudige uitrol door stateless service-instances; state wordt in expliciete data stores of messaging vastgelegd.
  Verwijzing: Kwaliteitseisen – Beschikbaarheid & Schaalbaarheid (profielservicedocs/03-kwaliteitseisen.md).

• Auditability als first-class concern
  Alle muterende acties en reads)worden vastgelegd ten behoeve van transparantie.
  Verwijzingen: ADR 0005, ADR 0007, ADR 0010. Zie ook Beperkingen - Juridisch en compliance (profielservicedocs/04-beperkingen.md).

• Het wiel niet opnieuw uitvinden
  Voorkeur voor hergebruik van standaarden, componenten en SDK’s boven maatwerk, tenzij harde eisen dit verhinderen.
  Verwijzingen: ADR’s en koppelingen met OpenZaak/OpenKlant (ADR 0004), NL Design System (ADR 0009).

• Gemeenschappelijke aanpak voor foutafhandeling, logging en tracing
  Eenduidige error-responses op API’s, centrale correlatie-ID, gestructureerde logging en distributed tracing.
  Verwijzing: Kwaliteitseisen – Observeerbaarheid (profielservicedocs/03-kwaliteitseisen.md), ADR 0010.

• Domeinmodel: rijk waar nodig, anemisch waar passend
  De Profielservice hanteert een pragmatische domeinstrategie op basis van boundedcontexts.
  Domeingebieden met niet-triviale bedrijfs- of wettelijke regels (zoals profielbeheer, autorisatie van dienstverleners en privacy/toestemming) gebruiken een rijk domeinmodel waarin invarianten expliciet worden afgedwongen.
  Domeingebieden die primair technisch of CRUD-gedreven zijn (zoals identiteitskoppelingen en auditlogging) hanteren een anemisch domeinmodel om complexiteit te beperken.

• Consistente naamgeving en API-conventies
  RESTful paden, HTTP-methoden semantisch correct, duidelijke statuscodes en foutstructuren.
  TODO: API style guide toevoegen? Of vinden we dat te veel van het goede?

• Koppelen via officiële API’s en registers
  Integraties met o.a. KvK en andere bronnen verlopen via hun officiële API-standaarden.
  Verwijzing: Kwaliteitseisen – Interoperabiliteit & Open Standaarden.

Software architectuur

Systeem Landschap diagram

De Systeem landschap diagram geeft een overzicht van alle actoren binnen het geprojecteerde landschap.
Dus niet alleen de Profiel Service, maar ook de systemen waarmee deze direct of indirect verbonden mee is.
Het laat hoogover zien wat benodigd is voor om op verschillende manieren (scenario 2,8 en 9) notificaties te verzenden.

Systeem Container diagram

Dit diagram toont het containerniveau van de Profiel Service en de systemen waarmee deze interageert. De Profiel Service bestaat uit een service-laag met een achterliggende database. Daarnaast raadpleegt de service het Handelsregister, om twee redenen:

1. Het tonen van bedrijfsinformatie aan zakelijke gebruikers via MijnOverheid Zakelijk.
2. Het verstrekken van adresgegevens aan de Berichtenbox voor Burgers en Ondernemers (BBO), wanneer deze daar om vraagt.

Code

Profiel Beheren

Hierin staan de patronen beschreven over hoe een zakelijke gebruiker zijn profiel zou beheren.

Profiel bekijken

sequenceDiagram
    actor ZakelijkGebruiker
    ZakelijkGebruiker->>MijnOverheid Zakelijk: Navigeert naar Contactgegevens
    activate MijnOverheid Zakelijk
    MijnOverheid Zakelijk->>Profiel service:Haalt contactgegevens op
    deactivate MijnOverheid Zakelijk
    activate Profiel service
    Profiel service->>Logboek Dataverwerking: READ log wegschrijven
    deactivate Profiel service
    activate Logboek Dataverwerking
    Logboek Dataverwerking-->>Profiel service: Ok
    deactivate Logboek Dataverwerking
    activate Profiel service
    Profiel service-->>MijnOverheid Zakelijk: Geeft contactgegevens terug
    deactivate Profiel service
    activate MijnOverheid Zakelijk
    MijnOverheid Zakelijk-->>ZakelijkGebruiker: Ziet zakelijke contactgegevens
    deactivate MijnOverheid Zakelijk

Email updaten & verifiëren

sequenceDiagram
    actor ZakelijkGebruiker
    ZakelijkGebruiker->>MijnOverheid Zakelijk: Update email Request
    activate MijnOverheid Zakelijk
    MijnOverheid Zakelijk->>Profiel service: Verstuurt email update
    deactivate MijnOverheid Zakelijk
    activate Profiel service
    participant AuditLog@{ "type" : "database" }
    participant EmailVerificatieService
    Profiel service->>AuditLog: 'Update aangevraagd'-log opslaan
    deactivate Profiel service
    activate AuditLog
    AuditLog-->>Profiel service: Ok
    deactivate AuditLog
    activate Profiel service
    Profiel service->>EmailVerificatieService: Start verificatieprocess
    deactivate Profiel service
    activate EmailVerificatieService
    EmailVerificatieService-->>ZakelijkGebruiker: Verstuur mail met verificatiecode
    deactivate EmailVerificatieService
    activate ZakelijkGebruiker
    ZakelijkGebruiker-)MijnOverheid Zakelijk: Verifieer email verificatiecode
    deactivate ZakelijkGebruiker
    activate MijnOverheid Zakelijk
    MijnOverheid Zakelijk->>Profiel service: Verstuurt verificatie verzoek
    deactivate MijnOverheid Zakelijk
    activate Profiel service
    Profiel service->>EmailVerificatieService:  Verifieer verificatie verzoek
    deactivate Profiel service
    activate EmailVerificatieService
    EmailVerificatieService-->>Profiel service: Bevestig verificatie
    deactivate EmailVerificatieService
    activate Profiel service
    Profiel service->>AuditLog: 'Update geverifieerd'-log opslaan
    deactivate Profiel service
    activate AuditLog
    AuditLog-->>Profiel service: Ok
    deactivate AuditLog
    activate Profiel service
    Profiel service-->>MijnOverheid Zakelijk: Profiel gegevens
    deactivate Profiel service
    activate MijnOverheid Zakelijk
    MijnOverheid Zakelijk-->>ZakelijkGebruiker: Succes pagina
    deactivate MijnOverheid Zakelijk

Authenticatie

Hierin staan de patronen beschreven over hoe het inlog process van een zakelijke gebruiker of organisatie zou verlopen. Aan het einde van dit hoofdstuk worden de te verwachten attributen per inlogmethode beschreven, met daarbij aangegeven welke verplicht of optioneel zijn. Eerst is een flow chart te zien die aangeeft wat de ondernemer kan verwachten aan de hand van de inlogmethode die hij/zij gebruikt.

    flowchart TD;
    %% Trigger
        TRIGGER([De ondernemer wilt zijn contactgegevens updaten])-->S1;

    %% DigId scenario
        S1[Het systeem laat de inlog opties zien: 1. Digid, 2. eHerkenning, 3. eIDas als Burger 4. eIDas als Organisatie]-->S2;
        S2[De ondernemer kiest Digid]-->S3;
        S3[Het systeem met behulp van het BSN haalt hij de relevant KVK's op bij de KVK-BSN api.];
        S3-->SUCCESS_DigId;

    %% eHerkenning scenario
        S1-->EXT2a1;
        EXT2a1[De ondernemer kiest eHerkenning]-->EXT2a2;
        EXT2a2[Het systeem haalt de KVK & BSN uit de eHerkenning. Voor BSN komt die uit NIN & NIN_TYPE.]-->EXT2a3;
        EXT2a3[OPTIE: Het systeem gebruikt het BSN om de andere KVK's op te halen bij de KVK-BSN api??.];
        EXT2a2-->SUCCESS_eHerkenning;
        EXT2a3-->SUCCESS_eHerkenning;

    %% eIDas scenario
        S1-->EXT3a1;
        EXT3a1[De ondernemer kiest eIDas Burger]-->EXT3a2;
        EXT3a2[Het systeem haalt de Person Identifier, en optioneel Representative Person Identifier uit eIDas.];
        EXT3a2-->SUCCESS_eIDas_Burger;

        S1-->EXT4a1;
        EXT4a1[De ondernemer kiest eIDas Organisatie]-->EXT4a2;
        EXT4a2[Het systeem haalt de Legal Person Identifier, en optioneel Legal Entity Identifier uit eIDas.];
        EXT4a2-->SUCCESS_eIDas_Organisatie;

        SUCCESS_DigId([De ondernemer kan zijn contactgegevens updaten voor zichzelf en al zijn ondernemingen]);
        SUCCESS_eHerkenning([De ondernemer kan zijn contactgegevens updaten voor zichzelf en 1 onderneming]);
        SUCCESS_eIDas_Burger([De ondernemer kan zijn contactgegevens updaten voor deze eIDas Person Identifier]);
        SUCCESS_eIDas_Organisatie([De ondernemer kan zijn contactgegevens updaten voor deze eIDas Legal Person Identifier]);

DigiD

eHerkenning

eIDas

Persoon

Organisatie

Regels

Data

Gegevensmodel

Het gegevensmodel van de ProfielService is opgebouwd rond de entiteiten PARTIJ en CONTACTGEGEVEN.

1. PARTIJ is de basis van een natuurlijke persoon of rechtspersoon. Een partij kan één of meerdere identificaties hebben, zoals BSN, KVK, RSIN of andere vormen van identificatie.
2. CONTACTGEGEVEN legt vast hoe en via welk kanaal een partij gecontacteerd kan worden door een dienst of organisatie.

Hiermee kunnen burgers en ondernemers vastleggen hoe zij gecontacteerd willen worden, bijvoorbeeld via e-mail of telefoon.

Ter ondersteuning van deze kernfunctionaliteit zijn vier aanvullende entiteiten toegevoegd: IDENTIFICATIE, VOORKEUR, DIENSTVERLENER en DIENSTVERLENER_AFDELING.

Hieronder volgt een tabel met de definities die wij hanteren voor deze entiteiten.

PARTIJ

CONTACTGEGEVEN

IDENTIFICATIE

VOORKEUR

DIENSTVERLENER

DIENST

Het onderstaande diagram geeft de structuur van het gegevensmodel weer, inclusief de relaties tussen PARTIJ, VOORKEUR, CONTACTGEGEVEN, DIENSTVERLENER, en DIENST.

erDiagram
    PARTIJ {
        int Id PK "NOT NULL"
    }

    CONTACTGEGEVEN {
        int Id PK "NOT NULL"
        int PartijId FK "NOT NULL"
        id Scope FK ""
        enum Taal
        enum ContactType "NOT NULL"
        text Waarde "NOT NULL"
        bool IsGeverifieerd "NOT NULL"
        date GeverifieerdAt "NOT NULL"
    }

    VOORKEUR {
        int PartijId PK,FK "NOT NULL"
        enum VoorkeurType PK "NOT NULL"
        text Waarde "NOT NULL"
    }

    IDENTIFICATIE {
        int PartijId PK,FK "NOT NULL"
        enum IdentificatieType PK "NOT NULL"
        text IdentificatieNummer PK "NOT NULL"
    }

    DIENSTVERLENER {
        int Id PK "NOT NULL"
        string Naam "NOT NULL"
    }

    DIENSTVERLENER_AFDELING {
        int Id PK "NOT NULL"
        int DienstverlenerId FK "NOT NULL"
        string Beschrijving ""
    }

    %% Relationships
    PARTIJ ||--|{ IDENTIFICATIE : "PartijId"
    PARTIJ ||--o{ VOORKEUR : "PartijId"
    PARTIJ ||--o{ CONTACTGEGEVEN : "PartijId"
    DIENSTVERLENER_AFDELING ||--o{ CONTACTGEGEVEN : "ScopeId"
    DIENSTVERLENER ||--|{ DIENSTVERLENER_AFDELING : "DienstverlenerId"

Data Transfer Object (DTO)

Wanneer de profiel-service wordt bevraagd, kan onderstaand DTO als response worden verwacht:

YAML

id: 1
identifier_type: BSN
identifier_id: "123456789"
contactvoorkeuren:
  - id: 101
    type: EMAIL
    waarde: rvo-afdeling@bedrijf.nl
    scope: ZAKELIJK
    voor_partij_id: 1001
    dienst_type: "0000000123"
    geverifieerd_at: "2025-11-03T12:00:00Z"

  - id: 102
    type: POST
    waarde:
      ter_attentie_van: "Robbert"
      straat: Wilhelminastraat
      huisnummer: 52
      postcode: "2215PA"
      plaats: Den Haag
      land: Nederland
    scope: ZAKELIJK
    voor_partij_id: 1001
    dienst_type: "0000000456"
    geverifieerd_at: "2025-11-03T12:00:00Z"

JSON

{
  "id": 1,
  "identifier_type": "BSN",
  "identifier_id": "123456789",
  "contactvoorkeuren": [
    {
      "id": 101,
      "type": "EMAIL",
      "waarde": "rvo-afdeling@bedrijf.nl",
      "scope": "ZAKELIJK",
      "voor_partij_id": 1001,
      "dienst_type": "0000000123",
      "geverifieerd_at": "2025-11-03T12:00:00Z"
    },
    {
      "id": 102,
      "type": "POST",
      "waarde": {
        "ter_attentie_van": "Robbert",
        "straat": "Wilhelminastraat",
        "huisnummer": 52,
        "postcode": "2215PA",
        "plaats": "Den Haag",
        "land": "Nederland"
      },
      "scope": "ZAKELIJK",
      "voor_partij_id": 1001,
      "dienst_type": "0000000456",
      "geverifieerd_at": "2025-11-03T12:00:00Z"
    }
  ]
}

Sequentiediagrammen

De volgende diagrammen illustreren de belangrijkste interacties met de ProfielService.

1. Dienstverlener bevraagt de ProfielService
   In dit scenario vraagt een dienstverlener de contactvoorkeuren op van een ondernemer of onderneming.
   Deze informatie kan de dienstverlener dan gebruiken om kennisgevingen en/of attenderingen correct af te kunnen leveren.

sequenceDiagram
    participant Dienstverlener
    participant Profiel as Profiel Service

    Dienstverlener->>Profiel: GET contactvoorkeuren Bsn en/of KvK
    activate Profiel
    Profiel-->>Dienstverlener: Contactvoorkeur(en) + Bsn
    deactivate Profiel

2. Ondernemer bekijkt en wijzigt contactvoorkeuren
   Dit scenario toont hoe een ondernemer via het MOZa-portaal zijn eigen contactvoorkeuren kan inzien en aanpassen.
   Afhankelijk van de loginmethode (bijv. DigiD of eHerkenning) worden de relevante ondernemingen opgehaald, waarna de ondernemer zijn voorkeuren per onderneming kan beheren.
   Na het aanpassen van een voorkeur wordt deze wijziging via de ProfielService opgeslagen, en indien van toepassing geverifieerd.

sequenceDiagram
    actor Ondernemer
    participant MOZa as MOZa Portaal
    participant KvK as KvK
    participant Profiel as Profiel Service

    Ondernemer->>MOZa: Logt in
    activate MOZa

    alt Als login via DigiD
        MOZa->>KvK: Haal ondernemingen op voor BSN
        deactivate MOZa
        activate KvK
        KvK-->>MOZa: Geeft ondernemingen terug (KvK-nummers)
        deactivate KvK
        activate MOZa
    end

    MOZa->>Ondernemer: Toon Profiel Pagina
    Ondernemer->>MOZa: Opent pagina 'Contactvoorkeuren'

    MOZa->>Profiel: GET contactvoorkeuren (BSN + KvK)
    deactivate MOZa
    activate Profiel
    Profiel-->>MOZa: Contactvoorkeuren terug
    deactivate Profiel
    activate MOZa

    MOZa->>Ondernemer: Toon pagina 'Contactvoorkeuren'

    Ondernemer->>MOZa: Past contactvoorkeur aan

    MOZa->>Profiel: PATCH contactvoorkeur (BSN + KvK)
    deactivate MOZa
    activate Profiel
    Profiel-->>MOZa: Ok (voorkeur bijgewerkt)
    deactivate Profiel
    activate MOZa

    MOZa-->>Ondernemer: Toont bevestiging
    deactivate MOZa

Deze scenario’s vormen de basis voor de interacties tussen de ProfielService, dienstverleners en eindgebruikers binnen de keten.

Deployment

View

De deployment view van de Profiel Servie is hieronder te vinden, deze bevat uiteindelijk maar 2 containers. De eerste is de Profiel Service zelf, met daarin de API-componenten en business logica, en de tweede is de bijbehorende postgresql database.

Omgeving

De omgeving is gehost op het Standaard Platform, specifiek in het TEST cluster van Openshift in de logius-moz-poc namespaces.

Broncode

De broncode van de applicatie is open-source beschikbaar op GitHub.
De infrastructuur files staat op de private gitlab server van het Standaard Platform.

Beheer en Support

De kans is momenteel aannemelijk dat de hosting hiervan uiteindelijk bij Logius terecht komt, daardoor hebben wij besloten de Profiel Service in Java/Quarkus op te zetten wat aansluit bij hun tech stack.

Hosting Standaard Platform

De omgeving wordt gehost door het Standaard Platform van Logius. Incidenten en wijzigingen kunnen, met de juiste rechten, worden ingeschoten via Topdesk: https://topdesk.sp-cloudservices.nl/tas/public/login/form.

Benodigde accounts

• Logius VPN
• Logius GitLab
• GitHub: https://github.com/