Certificaatvereisten en voorbeeld

Om toegang te verkrijgen tot Ons API, vereisen we dat requests getekend zijn middels een SSL-client-certificaat getekend door onze eigen Certificate Authority. Deze certificaten identificeren de connector en de omgeving van de zorgorganisatie waarop de requests worden gedaan.

Certificaat koppelproces
Zie voor de uitleg van het aanvraag- en koppelproces het artikel: Certificaten beheren / koppelen.

CSR vereisten

Elke CSR die ter ondertekening aangeboden wordt, dient te voldoen aan deze vereisten:

Key-length van tenminste 4096 bits.
CN, OU, O, L, ST, C en e-mail-adres zijn gevuld.
CN is opgesteld volgens de conventie; {technische_naam_connector}-{customer_code}-{identificatie}
- Technische_naam_connector
  Technische naam van de connector. Kan afwijken van de weergegeven naam van de connector. Alleen lowercase karakters: a-z, 0-9 en _.
- Customer_code
  De klantcode/customer code die voor die omgeving geldt. Voor development-doeleinden is deze: TE1002. Zie ook: Certificaten beheren / koppelen.
- Identificatie
  Vrij tekstveld, zoals staging, production, id2431. Alleen de volgende karakters: a-z, A-Z, 0-9, en _.
- Geldige voorbeelden:
  - hr_integration-TE1002-free_text
  - finance_integration-DF0000-production

Technische details

TLS

De minimale TLS versie is 1.2.
Het framework waarvan je gebruik maakt, moet een SNI-extensie sturen tezamen met de TLS handshake.

Geldige ciphers
Elk van onderstaande ciphers kan gebruikt worden:

ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-ECDSA-CHACHA20-POLY1305
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-CHACHA20-POLY1305
DHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES128-GCM-SHA256

CA Chain
Als je framework, platform of ontwikkeltaal de volledige CA-chain vereist, dan is deze hier te verkrijgen:

CSR genereren

We raden aan om OpenSSL te gebruiken. Met OpenSSL kan je met het volgende commando een CSR genereren:

openssl req -out my_connector-TE1002-example.csr -new -newkey rsa:4096 -nodes -keyout my_connector-TE1002-example.key

OpenSSL zal vragen om aanvullende informatie.

Gebruik een CN die voldoet aan de vereisten die eerder in dit artikel staan beschreven.

Vervolgens zullen een CSR en KEY-bestand gegenereerd worden. Het is erg belangrijk dat het KEY-bestand veilig opgeslagen en niet gedeeld wordt! Deel dit bestand ook niet met Nedap. Mocht het bestand op een gegeven moment onverhoopt toch gedeeld worden, schakel dan het certificaat in Ons API Dashboard uit en informeer Nedap.

Het CSR-bestand dient geüpload te worden in het Ons API Dashboard Certificaten beheren / koppelen. Daarna ontvang je van ons een PEM-bestand, waarmee je calls kunt doen.

Gebruik je een andere tool dan OpenSSL (bijvoorbeeld BouncyCastle library), zorg er dan voor dat je de meest recente versie van die tool gebruikt. Oudere versies genereren mogelijk ongeldige CSR’s die niet door ons ondertekend kunnen worden.

Certificaat testen

Je kunt het certificaat testen door een GET-request te doen naar de /ping endpoint op Ons API. Gebruik de URL die overeenkomt met de omgeving waar het certificaat voor is bestemd; zie ook: API properties.

Voorbeeld: GET https://api-development.ons.io/ping
Resultaat:
- 200: Het certificaat werkt.
- 403: Het certificaat werkt niet in combinatie met de opgegeven URL.

Als je test met curl op Windows, zorg dan voor een recente versie van curl. Vaak is versie 7.55.1 geïnstalleerd, welke niet goed omgaat met client certificaten.