SURFcertificaten
Child pages
  • REST API
Skip to end of metadata
Go to start of metadata

De meeste functies van Sectigo Certificate Manager (SCM) kunnen ook via een REST API worden gebruikt.

De documentatie hiervoor vind je op de Sectigo Knowledge Base in het document "
SCM - Sectigo Certificate Manager REST API". Dit is een HTML file met een beschrijving van alle interfaces.

Om gebuik te maken van de API moet in SCM een en ander worden geconfigureerd:

  • Maak een RAO admin account aan voor gebruik alsl API user. Het account moet hiervoor de juiste RAO Admin roles hebben (SSL, Client Certificate, etc).
    • Let op: voordat dit account gebruik kan worden moet eerst met de bijbehorende credentials worden ingelogd in SCM om het wachtwoord aan te passen.
    • Het wachtwoord dient uit maximaal 32 karakters te bestaan en moet niet-alfanumerieke karakters bevatten.
  • Requests moeten eerst goedgekeurd worden in SCM voordat het certificaat wordt uitgegeven. Als je wilt dat dit automatisch gebeurt, vink dan bij Privileges aan "Allow SSL auto approve".
  • Het is verstandig daarna login via de browser uit te zetten door de checkbox "WS API use only" aan te vinken. Als dat niet lukt: mail een MRAO via scs-ra@surfnet.nl om dat voor je te doen.

  • Vervolgens moet de API worden geactiveerd voor jouw organisatie, via Settings | Organizations. Edit de gewenste organisatie en de gewenste API (bij voorbeeld SSL Certificate), en vink de checkbox bij “Web API” 


    • Er verschijnt een tekstveld voor "Secret key". Deze wordt alleen gebruikt voor de Web Services (SOAP) API, niet voor de REST API. Je kunt hier iets willekeurigs invullen (mits voldoende entropie).

  • De API is nu klaar voor gebruik.

HTTP headers

De gebruikersnaam en wachtwoord voor de API moeten via custom HTTP headers worden verstuurd (via de headers login respectievelijk password), evenals de SCM account URI (via customerUri de header). Voor de SURFnet instance is die laatste altijd dezelfde: surfnet.

Een voorbeeld HTTP header file:

HTTP header file 
Accept: application/json;charset=utf-8
Content-Type: application/json;charset=utf-8
customerUri: surfnet
login: <your API user login>
password: <your API user password>

Note: header files are supported by curl starting with version 7.55.0 (check using curl -V).

SSL Certificaat aanvragen

Als voorbeeld enroll/collect/list SSL certificaat. Voor andere cerificaattypen: zie de documentatie.

Voor OV en EV certificaen moeten de organisatie en domeinnamen vooral gevalideerd zijn. De aanvraag wordt in JSON formaat verstuurd en bevat minimaal

  • een Certificate Signing Request (CSR),
  • een identifier (orgID) voor de organisatie (voor het O attribuut in het X.509 certificaat),
  • een identifier voor het type certificaat.

De orgID is op te zoeken via SCM, of via de organization API.

Voorbeeld (met curl als HTTP client, waarbij de HTTP headers uit de file headers worden gelezen):

$ curl -H @headers https://cert-manager.com/api/organization/v1
[
  {
    "id": 12345,
    "name": “Example Org",
    "certTypes": [
      "SMIME",
      "SSL"
    ],
    "departments": []
  }
]

Het orgID is in dit voorbeeld dus 12345.

De identifiers voor de verschillende types certificaten kunnen worden opgevraagd via de types API:

Beschikbare typen SSL certificaten 
$ curl -s https://cert-manager.com/api/ssl/v1/types -H @headers | jq -r 'map( [.id, .name, (.terms | join(","))]) | .[]  | @tsv'
425	GÉANT Unified Communications Certificate	365,730
426	GÉANT OV Multi-Domain	365,730
427	GÉANT EV SSL	365,730
428	GÉANT EV Multi-Domain	365,730
429	GÉANT IGTF Multi Domain	365,395
424	GÉANT Wildcard SSL	365,730
423	GÉANT OV SSL	365,730

Een request voor een SSL cerificaat ziet er bijvoorbeeld als volgt uit:

{
  "orgId": 12345,
  "csr": "-----BEGIN CERTIFICATE REQUEST——\nMII.. .”,
  "certType": 423,
  "term": 365
}

Voorbeelden

Een voorbeeld van het gebruik van de enroll en collect APIs:

Aanvraag van een server certificaat:
$ cat enroll.json 
{
  "orgId": 12345,
  "externalRequester": "you@example.edu",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICaDCCAVACAQAwIzEhMB8GA1UEAwwYdGVzdC5z ... 6rDasA=\n-----END CERTIFICATE REQUEST-----\n",
  "certType": 423,
  "comments": "enroll via API",
  "term": 365
}

$ curl -sH @headers https://cert-manager.com/api/ssl/v1/enroll -X POST -d @enroll.json
{"renewId":"AQIDBAUGBwgJCgsMDQ4P","sslId":1230789}

$ curl -sH @headers https://cert-manager.com/api/ssl/v1/collect/1230789/pem
-----BEGIN CERTIFICATE-----
MIIENjCCAx6gAwIBAgIBATANBgkqhkiG9w0BAQUFADBvMQswCQYDVQQGEwJTRTEUMBIGA1UEChML
...
LsRwKb+Zf9rO7f967R+iOnkmNlTUjdxMDRs=
-----END CERTIFICATE-----

Opmerkingen:

  • De collect call ondersteunt verschillende encodings. De PEM encoding hierboven levert momenteel certificaten in omgekeerde volgorde (van root naar end entity). De PKCS#7 encoding levert wel de juiste volgorde (van end entity naar root). Om te converteren naar PEM encoding:
    curl -sH @headers https://cert-manager.com/api/ssl/v1/collect/NNNNNNN/base64 | openssl pkcs7 -print_certs
    waarbij NNNNNNN het sslId is.
  • Voor multi-domain certificaten kunnen Subject Alternate Names op verschillende manieren worden toegevoegd
    • in het CSR, bij voorbeeld middels openssl: openssl req -new -key key.pem -subj "/CN=example.edu" -addext "subjectAltName = DNS:www.example.edu"
    • in het request, via de subjAltNames key in de JSON body.

Libraries

Foutmeldingen

{"code":-1021,"description":"This operation cannot be performed for Organization 'Example Og'."}

Controleer of je de API enabled hebt middels het aanvinken van "Web API" in de organisation settings.

{"code":-23,"description":"The certificate hasn't been approved yet!"}

Wacht tot een RAO de aanvraag heeft goedgekeurd, of zorg dat dit automatisch gebeurt door de Privileges van het API account uit te breiden met "Allow SSL auto approve".

{"code":-16,"description":"Unknown user"}

Onjuiste login of password

{"code":-16,"description":"Invalid auth data"}

Probleem met authenticatie (anders dan login/password) - check HTTP headers (zie ook opmerking hierboven over curl versie).


  • No labels