Digikoppeling

Digikoppeling

Implementeer beveiligde system-to-system communicatie tussen Nederlandse overheidsorganisaties.

Bron: Logius — Digikoppeling | GitHub | Forum Standaardisatie

Overzicht

Koppelvlakprofielen — vergelijking

Digikoppeling kent drie koppelvlakprofielen. Kies op basis van je use case.

Profielkeuze — beslisboom

Nieuw koppelvlak?
├── Ja → Synchroon request-response voldoende?
│   ├── Ja → REST API profiel (aanbevolen)
│   └── Nee → Gegarandeerde aflevering nodig?
│       ├── Ja → ebMS2 profiel
│       └── Nee → REST API profiel met async patroon
└── Nee → Bestaand SOAP-koppelvlak?
    ├── Ja → WUS profiel (onderhoud)
    └── Nee → Bestaand MSH-koppelvlak → ebMS2 profiel (onderhoud)

REST API profiel

Het REST API profiel volgt de NL API Design Rules en gebruikt TLS met PKIoverheid client-certificaten voor authenticatie.

Python voorbeeld met httpx en client-certificaat

import httpx

# PKIoverheid client-certificaat voor mutual TLS
client_cert = ("client.crt", "client.key")
ca_bundle = "/etc/ssl/certs/staat-der-nederlanden-root.pem"

client = httpx.Client(
    cert=client_cert,
    verify=ca_bundle,
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    timeout=30.0,
)

# Voorbeeld: opvragen gegevens bij andere overheidsorganisatie
response = client.get(
    "https://api.organisatie.nl/v1/resource",
    headers={"X-Correlation-ID": "uuid-voor-traceerbaarheid"},
)
response.raise_for_status()
data = response.json()

Verplichte headers (REST profiel)

WUS profiel

Het WUS profiel is gebaseerd op SOAP 1.1/1.2 met WS-Security en WS-Addressing. Gebruikt PKIoverheid-certificaten voor ondertekening en encryptie op berichtniveau.

SOAP-bericht met WS-Security headers

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
               xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
               xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsa:To>https://service.organisatie.nl/wus/endpoint</wsa:To>
    <wsa:Action>urn:opvragenGegevens</wsa:Action>
    <wsa:MessageID>urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890</wsa:MessageID>
    <wsse:Security soap:mustUnderstand="1">
      <wsu:Timestamp wsu:Id="TS-1">
        <wsu:Created>2026-02-27T10:00:00Z</wsu:Created>
        <wsu:Expires>2026-02-27T10:05:00Z</wsu:Expires>
      </wsu:Timestamp>
      <wsse:BinarySecurityToken
        ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
        EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
        wsu:Id="X509-1"><!-- base64-encoded PKIoverheid certificaat --></wsse:BinarySecurityToken>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <!-- XML Signature over Body en Timestamp -->
      </ds:Signature>
    </wsse:Security>
  </soap:Header>
  <soap:Body wsu:Id="Body-1">
    <opvragenGegevensRequest xmlns="urn:example:service">
      <identificatie>123456789</identificatie>
    </opvragenGegevensRequest>
  </soap:Body>
</soap:Envelope>

ebMS2 profiel

Het ebMS2 profiel is gebaseerd op OASIS ebXML Messaging 2.0 en biedt gegarandeerde aflevering via MSH-software (MSH = Message Service Handler). De MSH verzorgt betrouwbare verzending, ontvangstbevestiging en opnieuw proberen bij fouten.

ebMS2 MessageHeader voorbeeld

<eb:MessageHeader xmlns:eb="http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd"
                  eb:version="2.0"
                  soap:mustUnderstand="1">
  <eb:From>
    <eb:PartyId eb:type="urn:osb:oin">00000001234567890000</eb:PartyId>
    <eb:Role>Zender</eb:Role>
  </eb:From>
  <eb:To>
    <eb:PartyId eb:type="urn:osb:oin">00000009876543210000</eb:PartyId>
    <eb:Role>Ontvanger</eb:Role>
  </eb:To>
  <eb:CPAId>cpa-organisatieA-organisatieB-v1</eb:CPAId>
  <eb:ConversationId>conv-2026-0001</eb:ConversationId>
  <eb:Service>urn:example:gegevensuitwisseling</eb:Service>
  <eb:Action>opvragenGegevens</eb:Action>
  <eb:MessageData>
    <eb:MessageId>msg-a1b2c3d4@organisatieA.nl</eb:MessageId>
    <eb:Timestamp>2026-02-27T10:00:00Z</eb:Timestamp>
  </eb:MessageData>
</eb:MessageHeader>

CPA (Collaboration Protocol Agreement)

Een CPA is een XML-contract tussen twee partijen dat vastlegt:

• PartyInfo: OIN en rollen van beide partijen
• ServiceBinding: welke services en actions beschikbaar zijn
• Transport: endpoints (URL's) en transportprotocol
• ReliableMessaging: retries, retry-interval, acknowledgments
• Security: welke certificaten voor signing en encryptie

CPA's worden bilateraal uitgewisseld en geconfigureerd in de MSH-software van beide partijen.

PKIoverheid-certificaten

Digikoppeling vereist PKIoverheid-certificaten voor alle profielen.

Python SSLContext configuratie

import ssl

def create_digikoppeling_ssl_context(
    client_cert: str,
    client_key: str,
    ca_bundle: str = "/etc/ssl/certs/staat-der-nederlanden-root.pem",
) -> ssl.SSLContext:
    """Maak een SSLContext aan voor Digikoppeling mutual TLS."""
    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
    ctx.minimum_version = ssl.TLSVersion.TLSv1_2

    # Laad PKIoverheid CA-keten voor server-verificatie
    ctx.load_verify_locations(ca_bundle)

    # Laad client-certificaat voor mutual TLS
    ctx.load_cert_chain(certfile=client_cert, keyfile=client_key)

    # Verifieer altijd het servercertificaat
    ctx.check_hostname = True
    ctx.verify_mode = ssl.CERT_REQUIRED

    return ctx

Diginetwerk

Diginetwerk is het besloten netwerk voor gegevensuitwisseling tussen overheidsorganisaties.

OIN (Organisatie-Identificatienummer)

Het OIN is de unieke identificatie van een organisatie binnen Digikoppeling.

Het OIN wordt opgenomen in het Subject.serialNumber-veld van PKIoverheid-certificaten en als PartyId in ebMS2-berichten.

Aansluitproces — 8 stappen

Implementatie-checklist

• OIN: OIN aangevraagd en geregistreerd in COR
• Certificaten: PKIoverheid-certificaten aangevraagd (TLS, signing, encryptie)
• Profiel: koppelvlakprofiel gekozen en afgestemd met ketenpartner
• TLS 1.2+: minimaal TLS 1.2 geconfigureerd, onveilige cipher suites uitgeschakeld
• Mutual TLS: client-certificaat configuratie getest
• Netwerk: Diginetwerk-aansluiting geregeld (indien Rijksoverheid)
• CPA: CPA uitgewisseld en geconfigureerd (alleen bij ebMS2)
• MSH-software: MSH-software geconfigureerd en getest (alleen bij ebMS2)
• Foutafhandeling: retry-logica en foutafhandeling geimplementeerd
• Logging: OIN-gebaseerde logging en MSH-traceerbaarheid ingericht
• Certificaatbeheer: verloopdatum monitoring en vernieuwingsproces ingericht
• Pre-productie: end-to-end test met ketenpartner succesvol afgerond

Gerelateerde skills

Meer informatie

• Logius — Digikoppeling — officieel beheerportaal
• Digikoppeling op GitHub — specificaties en profielen
• Forum Standaardisatie — Digikoppeling — pas-toe-of-leg-uit status
• PKIoverheid — certificaatinformatie en TSP-lijst
• Diginetwerk — informatie over het besloten overheidsnetwerk