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 onder Sectigo® Certificate Manager (SCM) REST API. Dit is een HTML file met een beschrijving van alle interfaces.
Om gebuik te maken van de API maak je in SCM een RAO account aan met als type 'API'. Je kan voor de contactgegevens van dit account gewoon je eigen naam invullen. Een 'standard' account is ook om te zetten naar een API account door deze te selecteren en op 'Change Account Type' te klikken.
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 de customerUri
header). Voor de SURF instance is die laatste altijd dezelfde: surfnet
.
Een voorbeeld HTTP header file:
Let op: header files zijn door curl ondersteund vanaf versie 7.55.0 (check met curl -V
).
SSL Certificaat aanvragen voorbeeld
Hieronder volgt een voorbeeld voor het aanvragen van een SSL certificaat. Meer voorbeelden zijn te vinden in de Sectigo REST API documentatie.
De organisatie en domeinnamen moeten vooraf 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):
Het orgID is in dit voorbeeld dus 12345.
De identifiers voor de verschillende types certificaten kunnen worden opgevraagd via de types API:
Een request voor een SSL certificaat 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-----
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
waarbijNNNNNNN
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.
- in het CSR, bij voorbeeld middels openssl:
Libraries
- Enkele scripts voor het automatiseren: https://gist.githubsslId.com/joostd/d2af94977b2bb53455b9146fbf2fb721
- Een python library die mogelijk interessant is voor het aanvragen van SSL certificaten: https://github.com/broadinstitute/python-cert_manager
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).