Update documentation

README.md

@@ -4,9 +4,11 @@ This repository contains the technical documentation for the 'Generieke Functies
 of the Ministry of Health, Welfare and Sport of the Dutch government.
 
 The documentation covers services and integration patterns for
-the GFModules platform. It is published as a static site using
+the Generieke Functies. It is published as a static site using
 [Hugo](https://gohugo.io).
 
+Read the [latest documentation](https://minvws.github.io/gfmodules-technische-documentatie/latest/).
+
 > [!CAUTION]
 >
 > ## Disclaimer

content/_index.md

@@ -1,3 +1,52 @@
 ---
 title: "Overzicht"
+hero_title: "Technische Documentatie Generieke Functies"
+description: "Technische uitleg van de Generieke Functies, met API-documentatie, integratie-instructies, ontwerpen en wijzigingshistorie."
 ---
+
+## Services
+
+{{< services >}}
+
+Voor meer informatie over generieke functies verwijzen we je naar
+[generiekefuncties.nl](https://www.generiekefuncties.nl/).
+
+---
+
+## Snel van start
+
+[Volledige documentatie →](/integration/)
+
+{{% service-cards type="quickstart" %}}
+
+{{% service-card type="quickstart" icon="📜" %}}
+### Aansluiten
+
+Zorg voor een PKIoverheid-certificaat, registreer je organisatie en test de verbinding.
+
+[Aansluitinstructies →](/integration/aansluiten/)
+{{% /service-card %}}
+
+{{% service-card type="quickstart" icon="👥" %}}
+### PRS aanroepen
+
+Vier gebruiksmogelijkheden, OAuth-instructies en de uitwerking van de geblindeerde OPRF-uitwisseling.
+
+[PRS-documentatie →](/integration/prs/)
+{{% /service-card %}}
+
+{{% service-card type="quickstart" icon="📱" %}}
+### NVI bevragen
+
+Instructies voor OAuth en het registreren en lokaliseren van gegevensbeschikbaarheid in de Nationale Verwijs Index.
+
+[NVI-documentatie →](/integration/nvi/)
+{{% /service-card %}}
+
+{{% /service-cards %}}
+
+---
+
+## Recente wijzigingen
+
+{{< changelog limit="3" >}}

content/changelog.md

@@ -1,5 +1,7 @@
 ---
 title: "Changelog"
-type: "page"
-layout: "changelog"
 ---
+
+Overzicht van wijzigingen in de API-documentatie van de Generieke Functies.
+
+{{< changelog filters="true" >}}

content/integration/_index.md

@@ -1,3 +1,71 @@
 ---
 title: "Integratie"
+heading: "Integratie-documentatie"
 ---
+
+Stap-voor-stap instructies voor het verbinden met de Generieke Functies.
+
+{{% card %}}
+### Hoe begin ik?
+
+Begin met de [aansluitinstructies](/integration/aansluiten/).
+Voor beide diensten heb je een PKIoverheid-clientcertificaat nodig. Registreer je organisatie en dit certificaat vooraf bij de
+beheerder van de betreffende dienst. In de voorbeelden haal je met het certificaat bij het
+OAuth-endpoint van de gekozen dienst een token op; met dat token en het certificaat roep je
+vervolgens die dienst aan.
+
+{{% columns %}}
+
+{{% column %}}
+#### PRS {#aansluitstappen-prs}
+
+1. [Aansluiten](/integration/aansluiten/)
+2. [Token via PRS OAuth](/integration/prs/#oauth-token)
+3. [PRS](/integration/prs/)
+{{% /column %}}
+
+{{% column %}}
+#### NVI {#aansluitstappen-nvi}
+
+1. [Aansluiten](/integration/aansluiten/)
+2. [Token via NVI OAuth](/integration/nvi/#oauth-token)
+3. [NVI](/integration/nvi/)
+{{% /column %}}
+
+{{% /columns %}}
+
+{{% /card %}}
+
+{{% service-cards %}}
+
+{{% service-card icon="📜" %}}
+### Aansluiten
+
+*Certificaat, registratie en verbinding*
+
+Bereid je aansluiting voor met een PKIoverheid-certificaat, registreer je organisatie en test de verbinding met de PRS of NVI.
+
+[Naar aansluitinstructies →](/integration/aansluiten/)
+{{% /service-card %}}
+
+{{% service-card icon="👤" icon-class="icon-prs" %}}
+### PRS
+
+*Pseudoniemendienst*
+
+De PRS biedt vier gebruiksmogelijkheden: omkeerbare pseudoniemen, niet-omkeerbare pseudoniemen, DigiD SAML-exchange en geblindeerde OPRF-uitwisseling. De documentatie beschrijft ook OAuth-toegang tot de dienst.
+
+[Naar PRS-documentatie →](/integration/prs/)
+{{% /service-card %}}
+
+{{% service-card icon="📑" icon-class="icon-nvi" %}}
+### NVI
+
+*Nationale Verwijs Index*
+
+De NVI-documentatie beschrijft het registreren en lokaliseren van gegevensbeschikbaarheid en het ontwerp voor privacybeschermde matching.
+
+[Naar NVI-documentatie →](/integration/nvi/)
+{{% /service-card %}}
+
+{{% /service-cards %}}

content/integration/aansluiten.md

@@ -0,0 +1,137 @@
+---
+title: "Aansluiten"
+type: "page"
+sections:
+  - id: aansluitstappen
+    title: "Aansluiten in vier stappen"
+  - id: certificaat
+    title: "PKIoverheid-certificaat"
+    children:
+      - id: private-key-beveiligen
+        title: "Beveilig je private key"
+  - id: registratie
+    title: "Organisatie en certificaat registreren"
+  - id: verbinding-testen
+    title: "Verbinding testen met mTLS"
+    children:
+      - id: verbinding-curl
+        title: "Met curl"
+      - id: metadata-healthchecks
+        title: "Metadata en healthchecks"
+      - id: verbinding-pkcs12
+        title: "Met een PKCS#12-bundle"
+      - id: pkcs12-aanmaken
+        title: "PKCS#12-bundle aanmaken"
+aliases:
+  - /integration/mtls/
+heading: "Aansluiten"
+---
+
+Om aan te sluiten op de PRS of NVI heb je een PKIoverheid-clientcertificaat nodig. Hieronder lees je hoe je de aansluiting voorbereidt, je organisatie registreert en de verbinding test.
+
+{{% card %}}
+
+### Aansluiten in vier stappen {#aansluitstappen}
+
+1. [Zorg voor een PKIoverheid-clientcertificaat](#certificaat) met de bijbehorende private key.
+2. [Registreer je organisatie en certificaat](#registratie) bij de beheerder van de dienst.
+3. [Test de mTLS-verbinding](#verbinding-testen) met de serveradressen.
+4. Volg de OAuth-instructies voor [PRS](/integration/prs/#oauth-token) of [NVI](/integration/nvi/#oauth-token) om een token op te halen en de dienst aan te roepen.
+
+{{% /card %}}
+
+{{% card %}}
+
+### PKIoverheid-certificaat {#certificaat}
+
+Vraag een PKIoverheid-certificaat aan dat geschikt is voor clientauthenticatie. Met dit certificaat identificeert je client zich bij de PRS of NVI.
+
+{{% columns %}}
+
+{{% column %}}
+
+#### Wat heb je nodig?
+
+- PKIoverheid-clientcertificaat (`.crt` of `.pem`)
+- Bijbehorende private key (`.key`)
+- Optioneel: PKCS#12-bundle (`.pfx` of `.p12`)
+
+{{% /column %}}
+
+{{% column %}}
+
+#### Meer informatie
+
+- [Wat is een PKIoverheidcertificaat?](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/wat-een-pkioverheidcertificaat)
+- [PKIoverheid-combinatiecertificaten voor client- en serverauthenticatie](https://www.logius.nl/onze-dienstverlening/toegang/pkioverheid/pkioverheid-behoudt-combinatiecertificaten-serverauth-en-clientauth)
+- [Organisaties die (gratis) testcertificaten aanbieden](https://github.com/pkioverheid/g4-trial#overview)
+
+{{% /column %}}
+
+{{% /columns %}}
+
+{{% notice title="Vereist PKIoverheid-certificaatprofiel" %}}
+
+Type: `G4 Private TLS Generic Devices Organization Validated Server` (`OID 2.16.528.1.1003.1.2.44.15.35.11`). Dit profiel ondersteunt clientauthenticatie (`clientAuth`) en serverauthenticatie (`serverAuth`). De voorbeelden gebruiken het certificaat voor clientauthenticatie bij mTLS.
+
+Organisatie-identificatie: **Organisatie-identificatienummer (OIN)**.
+
+{{% /notice %}}
+
+{{% notice title="Beveilig je private key" type="warn" id="private-key-beveiligen" %}}
+
+Sla de private key nooit op in versiebeheer. Gebruik een secrets-manager (Vault, AWS Secrets Manager, Azure Key Vault) of een OS-sleutelketen.
+
+{{% /notice %}}
+
+{{% /card %}}
+
+{{% card %}}
+
+### Organisatie en certificaat registreren {#registratie}
+
+Registreer je organisatie en het PKIoverheid-clientcertificaat dat je gebruikt vooraf bij de beheerder van de betreffende dienst. Rond deze registratie af voordat je een OAuth-token ophaalt of PRS/NVI aanroept.
+
+{{% /card %}}
+
+{{% card %}}
+
+### Verbinding testen met mTLS {#verbinding-testen}
+
+Bij gewone TLS verifieert alleen de cliënt de server. Bij **Mutual TLS (mTLS)** verifieert ook de server de cliënt aan de hand van een clientcertificaat. Voor de aansluiting gebruik je hiervoor het PKIoverheid-clientcertificaat. Een verbinding zonder geldig clientcertificaat wordt op transportniveau geweigerd.
+
+#### PKIoverheid-certificaat gebruiken
+
+Gebruik voor de mTLS-verbinding je PKIoverheid-clientcertificaat met volledige certificaatketen en de bijbehorende private key. De bestandsnamen hieronder zijn voorbeelden; vervang ze door de paden naar je eigen bestanden:
+
+- `client-cert.pem` — je PKIoverheid-clientcertificaat inclusief de volledige certificaatketen.
+- `client-key.pem` — de bijbehorende private key.
+
+#### Verbinding testen met curl {#verbinding-curl}
+
+Test het OAuth-endpoint van de dienst waarmee je wilt verbinden. Vervang de URL-placeholders in de voorbeelden door de serveradressen, inclusief `https://` en zonder afsluitende slash. Gebruik voor de API en de OAuth-service het bijbehorende serveradres.
+
+{{% service-examples "connection-curl" %}}
+
+#### Metadata en healthchecks {#metadata-healthchecks}
+
+De metadata- en health-endpoints hieronder vereisen mTLS. Een OAuth-token is niet nodig. Gebruik je PKIoverheid-clientcertificaat en de bijbehorende private key om de verbinding te testen.
+
+{{% service-examples "connection-metadata" %}}
+
+#### Verbinding testen met een PKCS#12-bundle (`.pfx` / `.p12`) {#verbinding-pkcs12}
+
+{{% service-examples "connection-pkcs12" %}}
+
+#### PKCS#12-bundle aanmaken {#pkcs12-aanmaken}
+
+```bash
+openssl pkcs12 -export \
+  -in    client-cert.pem \
+  -inkey client-key.pem \
+  -out   client.p12 \
+  -name  "gfmodules-client" \
+  -passout pass:geheimwachtwoord
+```
+
+{{% /card %}}