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:
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 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:
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> |
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
orgID
) voor de organisatie (voor het O attribuut in het X.509 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:
$ 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 } |
Een voorbeeld van het gebruik van de enroll en collect APIs:
$ 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----- |
Voor multi-domain certificaten kunnen Subject Alternate Names op verschillende manieren worden toegevoegd
openssl req -new -key key.pem -subj "/CN=example.edu" -addext "subjectAltName = DNS:www.example.edu"
subjAltNames
key in de JSON body.{"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.