Couriers¶
What is a Courier?¶
A Courier is a command line utility that runs on a target system to manage certificate lifecycle operations locally. Unlike a Bridge, which is a persistent daemon that receives jobs from the platform, a Courier is scheduled to run periodically — checking whether a certificate needs to be issued or renewed, performing the necessary operations, and then exiting.
The Courier is the primary mechanism for pull-based certificate delivery. It gives you precise control over where and how key material is generated, while the platform handles certificate signing and policy enforcement.
Certificate Provisioning with a Courier¶
Provisioning a certificate involves three steps:
| Step | What happens | Where it can run |
|---|---|---|
| 1. Key pair generation | A public and private key pair is created | Target system (via Courier) or platform |
| 2. CSR creation | A certificate signing request is generated from the key pair | Target system (via Courier) or platform |
| 3. Certificate issuance | The CSR is signed by a certificate authority | Platform CA or integrated external CA |
The Courier handles steps 1 and 2 locally on the target system when generate_keys_locally: true is set in its configuration. This keeps private key material on the host where the certificate will be used — it is never transmitted to the platform. The Courier then submits the CSR to the platform for signing, and retrieves the completed certificate once it is ready.
For environments where local key generation is not required, the Courier can submit a request to the platform and let the platform handle key generation. In this case, the private key is encrypted before it leaves the platform and can only be decrypted by the intended recipient. See Security and Architecture for details.
Connecting to the Platform¶
A Courier can reach the Zaita platform in two ways:
Directly — the Courier connects outbound to the Zaita SaaS endpoint for your region. This requires the host running the Courier to have outbound HTTPS access (port 443) to the internet.
Via a Bridge — the Courier connects to a Bridge deployed within your internal network. The Bridge proxies the request to the SaaS on the Courier's behalf. This allows Couriers to operate in network-restricted environments with no direct internet access — only outbound access to the Bridge host is required.
Routing Couriers through a Bridge is the recommended approach for production environments. It provides a single, controlled egress point and enables tighter network segmentation. See Bridges — Best Practices for network design guidance.
Authentication¶
Each Courier is registered in the platform under CLM → Couriers. The Courier record holds the credential configuration and controls which domains the Courier may request certificates for. The following authentication methods are supported:
| Method | Type | Recommended For |
|---|---|---|
| SPIFFE/SPIRE | Credential-less (federated) | Workloads with a SPIRE agent deployed |
Azure Workload Identity (azure_jwt) |
Credential-less (federated) | Workloads on Azure (VMs, AKS, App Service) |
Azure Arc (azure_arc) |
Credential-less (federated) | On-premises servers enrolled in Azure Arc |
| AWS IAM OIDC | Credential-less (federated) | Workloads on AWS or using IAM Roles Anywhere |
Generic OIDC JWT (oidc_oauth2) |
Credential-less (federated) | Custom or internal identity providers |
| X.509 Certificate | Credential-based (legacy) | Environments where federated identity is unavailable |
| Client ID / Secret | Credential-based (legacy) | Development or low-sensitivity environments only |
Credential-less federated identity methods are strongly preferred. They eliminate static credentials entirely, removing the risk of credential exposure and the operational burden of rotation. Legacy methods can be disabled at the organisation level if not in use. See Authentication for configuration details.
Domain Access Control¶
Every Courier is configured with an allowed domains list — the domain patterns the Courier is permitted to request certificates for. Patterns support wildcards (for example, *.example.com). Certificate requests that include a domain not covered by the allowed list are rejected before any job is dispatched.
This is configured when the Courier record is created in the portal and can be updated at any time from the Courier's management page.
Scheduling¶
The Courier is not a persistent agent. It is designed to be scheduled via a cron job (Linux) or Scheduled Task (Windows). On each run, the Courier checks the status of the configured certificate and acts only if action is required — issuing if no certificate exists, renewing if within the configured renewal threshold, or exiting immediately if the certificate is current.
A run frequency of every 12 hours is recommended for most deployments. Given that most runs will require no action, the CPU and network impact is minimal.
Certificate Orders¶
Each certificate generated by a Courier creates an order that is visible under Certificates → Orders in the portal. The Requested By column identifies whether an order was initiated by a Courier, an ACME client, or a portal user, giving operators a unified view of all certificate activity across the platform.
Supported Platforms¶
| Platform | Installation Format |
|---|---|
| Linux | .deb (Debian/Ubuntu), .rpm (RHEL/Fedora), standalone binary |
| Windows | .exe installer, standalone binary |
Bring Your Own Courier (BYOC)¶
The Zaita REST API is fully documented, enabling organisations to build custom courier implementations in any language. This is useful for integration with proprietary systems, non-standard deployment environments, or CI/CD pipelines where the standard Courier binary is not appropriate. See the Courier Configuration Reference for details on the API interaction model.