Mutual TLS

Require a client certificate on every call to the Signals API, issue and manage the certificates, and present one from curl, Node.js, Python or Java.

Learn how to require a client certificate on calls to the Signals API, on top of your credentials. Mutual TLS means the client proves who it is with a certificate, as the server does with its own. Ovok never holds your private key.

It guards every call to /v1/signals/api/* of your project's own Signals tenant. Hosts and routes do not change. With it on, Signals also presents its own client certificate on every webhook to your endpoints: see Webhooks over mutual TLS.

Turn it on

Save SIGNALS_MTLS_ENABLED on, in the Console under Signals › Settings or through the project settings API. Register a certificate first: without one the save answers 409 SETTING_NOT_AVAILABLE. Saving it on while any Signals webhook subscriber still has an http URL answers 409 WEBHOOKS_NOT_HTTPS and names each such subscriber, because Signals presents its client certificate over https only and would drop their events: move them to https, or delete them, first. Saving it off removes the requirement and keeps your certificates.

  1. 1Open Signals settings and enable mutual TLS.
  2. 2Your browser creates the key; Ovok issues the certificate.
  3. 3Download both. Future Signals calls must present the certificate.
SettingCertificate on the requestAnswer
OffAnyThe call is handled as usual.
OnNone403 SIGNALS_MTLS_REQUIRED
OnNot registered for the project, or expired403 SIGNALS_MTLS_CERTIFICATE_UNKNOWN
OnRegistered and validThe call is handled as usual.

environment in GET /v1/signals/certs says what the environment you call can do. forwardsCertificates must be true to turn the setting on; issues and registers say whether issuing and registering work. caCertificate is Ovok's CA, to verify Signals' webhook certificate against.

Manage client certificates

A project holds at most two certificates. In the Console, Signals › Settings issues one: your browser makes the key pair, sends Ovok only the signing request, and hands you the certificate and the key to download. The same is available over the API:

RouteWhat it does
GET /v1/signals/certsLists the certificates (sha256, serialNumber, subject, notAfter, registeredAt) and the environment.
POST /v1/signals/certsRegisters a certificate you hold. Send its PEM as certificate. It must be valid now, for client authentication, and issued by a CA Ovok trusts.
POST /v1/signals/certs/issueIssues a certificate from a CSR you send as PEM in csr, and registers it. The key is EC on P-256 or P-384, or RSA of at least 2048 bits.
DELETE /v1/signals/certs/:sha256Removes a certificate by its SHA-256 fingerprint. Calls presenting it are refused at once.
  • Who may call them. A project admin's bearer token, from a Practitioner session. A client application's credential answers 403, so it can't mint itself a certificate.
  • Issued certificates last six months. Ovok's CA signs a client-authentication certificate valid for six months, or until the CA itself expires if that comes first. The subject is CN=<tenant id>. Nothing else in the CSR is kept.
  • A certificate past notAfter stays listed until you remove it, but calls presenting it are refused.
curl --request POST 'https://api.sandbox.ovok.com/v1/signals/certs/issue' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data "{\"csr\": $(jq -Rs . < client.csr)}"
StatusCodeCause
409SIGNALS_TENANT_NOT_OWNThe project has no Signals tenant of its own.
409CERTIFICATE_ALREADY_REGISTEREDThat certificate is registered already.
409CERTIFICATE_LIMIT_REACHEDThe project holds two. Remove one first.
422CERTIFICATE_NOT_ACCEPTEDNot a PEM certificate, a CA certificate, not valid now, not for client authentication, or from a CA Ovok doesn't trust.
422CSR_NOT_ACCEPTEDNot a PEM CSR, a signature that does not verify, an unsupported key, or an EC key that spells out its curve: make it with -pkeyopt ec_param_enc:named_curve.
404CERTIFICATE_NOT_FOUNDNo certificate with that fingerprint.
501FEATURE_NOT_CONFIGUREDThe environment has no CA to register against or issue from.

Present the certificate

Send the certificate and its key on every call to /v1/signals/api/*. Your credentials don't change: the certificate is checked on top of them.

curl --get 'https://api.sandbox.ovok.com/v1/signals/api/alert' \
  --cert client.crt --key client.key \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}"

A proxy that ends TLS in front of your client drops the certificate: connect to the API host directly.

Webhooks over mutual TLS

With SIGNALS_MTLS_ENABLED on, Signals presents its own client certificate on every webhook it delivers to your subscribers, which must be https endpoints. With it off, deliveries carry no client certificate.

FieldValue
SubjectO=Ovok, CN=signals
Subject alternative nameurn:ovok:signals:<environment>
UsageClient authentication only
IssuerOvok's CA: environment.caCertificate in GET /v1/signals/certs, or Download Ovok's CA in the Console under Signals › Settings

To accept deliveries from Signals only:

  1. Ask for a client certificate on your webhook endpoint and verify it against Ovok's CA.
  2. Accept only the subject alternative name urn:ovok:signals:<environment>. Your project's own client certificates chain to the same CA, so the CA alone is not enough.
  3. Keep verifying the signature. The certificate proves who sent the delivery; the signature proves its body.

Signals' certificate is renewed every year with the same name and CA, so pin those rather than its fingerprint.

webhook-receiver.ts
import { readFileSync } from 'node:fs';
import { createServer } from 'node:https';
import type { TLSSocket } from 'node:tls';

const signalsName = `URI:${process.env.SIGNALS_WEBHOOK_NAME}`;

createServer(
  {
    key: readFileSync('server.key'),
    cert: readFileSync('server.crt'),
    ca: readFileSync('ovok-signals-ca.pem'),
    requestCert: true,
    rejectUnauthorized: true,
  },
  (req, res) => {
    const sender = (req.socket as TLSSocket).getPeerCertificate();
    if (sender.subjectaltname !== signalsName) {
      res.writeHead(403).end();
      return;
    }
    handleSignedDelivery(req, res);
  },
).listen(443);

handleSignedDelivery is your signature check and handler from Verify webhooks. Behind a load balancer that ends TLS, require the client certificate there and check the name in your app from the certificate it forwards.

Rotate without downtime

Two certificates may be registered at once, so a rotation needs no gap.

  1. Issue or register the new certificate.
  2. Move your clients to it.
  3. Remove the old one by its sha256. Calls presenting it are refused at once.

See also

Last updated on

On this page