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.

Aansluiten in vier stappen

  1. Zorg voor een PKIoverheid-clientcertificaat met de bijbehorende private key.
  2. Registreer je organisatie en certificaat bij de beheerder van de dienst.
  3. Test de mTLS-verbinding met de serveradressen.
  4. Volg de OAuth-instructies voor PRS of NVI om een token op te halen en de dienst aan te roepen.

PKIoverheid-certificaat

Vraag een PKIoverheid-certificaat aan dat geschikt is voor clientauthenticatie. Met dit certificaat identificeert je client zich bij de PRS of NVI.

Wat heb je nodig?

  • PKIoverheid-clientcertificaat (.crt of .pem)
  • Bijbehorende private key (.key)
  • Optioneel: PKCS#12-bundle (.pfx of .p12)

Meer informatie

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).

Beveilig je private key

Sla de private key nooit op in versiebeheer. Gebruik een secrets-manager (Vault, AWS Secrets Manager, Azure Key Vault) of een OS-sleutelketen.

Organisatie en certificaat registreren

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.

Verbinding testen met mTLS

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

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.

PRS
# Controleer of mTLS-handshake slaagt
curl -v \
  --cert client-cert.pem \
  --key  client-key.pem \
  "<prs-oauth-url>/oauth/.well-known/oauth-authorization-server"
NVI
# Controleer of mTLS-handshake slaagt
curl -v \
  --cert client-cert.pem \
  --key  client-key.pem \
  "<nvi-oauth-url>/oauth/.well-known/oauth-authorization-server"

Metadata en 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.

PRS
  • /oauth/.well-known/oauth-authorization-server — OAuth-servermetadata
  • /oauth/health — health check van de OAuth-service
  • /api/health — health check van de API
NVI
  • /oauth/.well-known/oauth-authorization-server — OAuth-servermetadata
  • /oauth/health — health check van de OAuth-service
  • /api/health — health check van de API

Verbinding testen met een PKCS#12-bundle (.pfx / .p12)

PRS
# Controleer de mTLS-verbinding met een PKCS#12-bundle
curl "<prs-api-url>/api/health" --cert-type P12 --cert "client.p12:<wachtwoord>"
NVI
# Controleer de mTLS-verbinding met een PKCS#12-bundle
curl "<nvi-api-url>/api/health" --cert-type P12 --cert "client.p12:<wachtwoord>"

PKCS#12-bundle aanmaken

openssl pkcs12 -export \
  -in    client-cert.pem \
  -inkey client-key.pem \
  -out   client.p12 \
  -name  "gfmodules-client" \
  -passout pass:geheimwachtwoord