Issue a client certificate from a CSR
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
Issues a client certificate for your current project from a certificate signing request (CSR), and registers it. Calls into Signals may then present it, and must once SIGNALS_MTLS_ENABLED is on.
Auth: A client credential cannot issue a certificate for itself. Scope: the caller's project (from the token).
Behaviour
- Make a key and a CSR on your side, and send the CSR as PEM in
csr. The private key never leaves your client. - The key must be an EC key on P-256 or P-384 that names its curve, or an RSA key of at least 2048 bits, and the CSR's signature must verify. Otherwise 422
CSR_NOT_ACCEPTED, with the reason. - Ovok's CA signs a certificate for client authentication only, valid for six months, or until the CA itself expires if that comes first. Its
notAfteris in the answer. Its subject isCN=<tenant id>and its subject alternative nameurn:ovok:signals-tenant:<tenant id>. Nothing else in the CSR is taken over. - The certificate counts towards the project's two: a third answers 409
CERTIFICATE_LIMIT_REACHED. - An environment with no CA set up to issue answers 501
FEATURE_NOT_CONFIGURED. If its CA has expired, Ovok registers nothing and answers 500INTERNAL_ERROR. - The answer is 201 with the registered certificate and its PEM in
certificate, andLocationnames it. - At 00:00 UTC, 14 days before the certificate expires, Ovok notifies the project's admins in the Console and mails them and its parent project's admins. A certificate registered closer to its expiry is mailed about at once; a removed one is not.
- To rotate: issue a new certificate, move your clients to it, then remove the old one.
Example
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes \ -keyout client.key -out client.csr -subj "/CN=client"curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d "{ \"csr\": $(jq -Rs . < client.csr) }" | jq -r .certificate > client.crtWho can call it: a project admin. See roles.
bearerAuthorizationBearer <JWT>application/json- body
csr*stringA PKCS#10 certificate signing request, PEM, made with the key your client will present.
1 <= length <= 16384The issued certificate, registered already, with its PEM in certificate. Location names it.
application/json- response
sha256*stringSHA-256 fingerprint of the certificate, lowercase hex: its id here.
serialNumber*stringsubject*stringnotAfter*stringWhen the certificate expires, ISO 8601. After it, calls with it are refused.
registeredAt*stringcertificate*stringThe issued client certificate, PEM. Present it with the key the CSR was made with.
curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \ -H 'Content-Type: application/json' \ -d '{ "csr": "string"}'{ "sha256": "string", "serialNumber": "string", "subject": "string", "notAfter": "string", "registeredAt": "string", "certificate": "string"}Register a client certificate POST
Registers a client certificate for your current project. Calls into Signals may then present it, and must once `SIGNALS_MTLS_ENABLED` is on. **Auth:** A client credential cannot register a certificate for itself. **Scope:** the caller's project (from the token). ## Behaviour - Send the certificate as PEM in `certificate`. Only its first certificate is read. Never send the private key: it stays with your client. - The certificate must be valid now, not a CA certificate, for client authentication (or have no extended key usage), and issued by a CA your Ovok environment trusts. Otherwise 422 `CERTIFICATE_NOT_ACCEPTED`, with the reason. - An environment with no CA set up for client certificates answers 501 `FEATURE_NOT_CONFIGURED`. - The same certificate twice answers 409 `CERTIFICATE_ALREADY_REGISTERED`; a third certificate 409 `CERTIFICATE_LIMIT_REACHED`. - The answer is 201 with the registered certificate, and `Location` names it. - At 00:00 UTC, 14 days before the certificate expires, Ovok notifies the project's admins in the Console and mails them and its parent project's admins. A certificate registered closer to its expiry is mailed about at once; a removed one is not. - To rotate: register the new certificate, move your clients to it, then remove the old one. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/signals/certs' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d "{ \"certificate\": $(jq -Rs . < client.crt) }" ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).
Remove a client certificate DELETE
Removes one of your current project's client certificates. From then on, calls presenting it are refused. **Scope:** the caller's project (from the token). ## Behaviour - `:sha256` is the certificate's fingerprint as `GET /v1/signals/certs` lists it. - An unknown fingerprint answers 404 `CERTIFICATE_NOT_FOUND`. - While `SIGNALS_MTLS_ENABLED` is on, the project's last certificate cannot be removed: 409 `LAST_CERTIFICATE_IN_USE`. Every call into Signals would be refused without one. Register another certificate, or turn mutual TLS off, first. - The answer is 204 with no body. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/signals/certs/3f6c0d2a9b8e7f1c4d5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f80912' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` **Who can call it:** a project admin. See [roles](/access-policies#who-can-call-a-route).