Setting Up a Courier¶

This guide covers creating a Courier record in the portal, installing the Courier binary, configuring it for your environment, and scheduling it to run automatically.

For an overview of what a Courier is and how it works, see Couriers — Introduction.

Prerequisites¶

Before you begin, ensure the following:

You are signed in to the Zaita web portal with the Deployment Administrator or Super Administrator role.
The target system has outbound HTTPS access (port 443) to your Zaita SaaS endpoint or to a Bridge deployed in your network.
You have determined which authentication method the Courier will use.

Step 1 — Create a Courier Record¶

Each Courier requires a record in the platform that controls its credentials and the domains it may request certificates for.

Navigate to CLM → Couriers in the web portal.
Select Add Courier.
Fill in the following fields:

Field	Required	Description
Name	Yes	A descriptive identifier, e.g. `courier-prod-web01`
Description	No	Optional notes for operators
Owner	No	Person or team responsible for this Courier
Contact Email	No	Email address for notifications or support queries
Status	Yes	Set to Active to enable the Courier immediately

Select an Authentication Method. The form displays the relevant configuration fields for the method you choose. The authentication method cannot be changed after the Courier record is saved — to switch methods, delete and recreate the Courier. See Authentication for all options.
Configure the Allowed Domains list. Add one or more domain patterns that this Courier is permitted to request certificates for. Both exact matches and wildcard patterns are supported:

Pattern	Matches
`api.example.com`	`api.example.com` only
`*.example.com`	`api.example.com`, `www.example.com`, etc. (not `example.com` itself)

Only domains registered under your tenant are accepted. The allowed domains list can be updated at any time from the Courier's management page.

Select Save.
For Client ID / Secret authentication: the client_id and client_secret are displayed once only after saving. Copy them immediately — the secret cannot be retrieved again. If lost, regenerate it from the Courier's management page.
For PKI Certificate authentication: upload the PEM-encoded X.509 client certificate. The certificate fingerprint is stored; the certificate itself is not returned in subsequent reads.
For all federated identity methods: only the Courier's UUID is needed in the Courier binary configuration — credentials are provided by your identity platform at runtime.

Step 2 — Install the Courier¶

Windows¶

Download the Courier installer (.exe) from the Zaita web portal under Downloads, or from https://www.zaita.com/courier/downloads.

Run the installer. The Courier binary is installed to:

C:\Program Files\Zaita\Courier\courier.exe

A sample configuration file is placed at:

C:\Program Files\Zaita\Courier\config.yaml

Permissions: The Courier must run with sufficient privileges to execute the on_success script — for example, to install certificates, update bindings, and restart services. It is strongly recommended to run the Courier under a Group Managed Service Account (gMSA) rather than a standard user account. For Microsoft IIS deployments, the gMSA requires permissions to: - Write to the certificate store - Update IIS bindings - Restart the IIS service

Linux¶

Download the appropriate package from the Zaita web portal under Downloads, or from https://www.zaita.com/courier/downloads.

Debian / Ubuntu:

sudo dpkg -i zaita-courier.deb

RHEL / Fedora / OpenSUSE:

sudo rpm -ivh zaita-courier.rpm

The Courier binary is installed to /usr/bin/zaita-courier. A sample configuration file is placed at /etc/zaita/courier/config.yaml.

Create a dedicated service account for the Courier with access restricted to the certificate output directory and any scripts it needs to execute:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin zaita-courier

Standalone Binary¶

If you prefer not to use an installer, download the standalone binary for your platform from https://www.zaita.com/courier/downloads. Place it in a directory of your choice and ensure the file is executable:

chmod +x zaita-courier

Step 3 — Configure the Courier¶

Copy the sample configuration file and edit it for your deployment. The full configuration reference is available at Courier Configuration Reference.

At minimum, configure the following sections:

api — the endpoint the Courier will connect to. Set base_url to your regional SaaS endpoint, or to your Bridge's hostname if routing through a Bridge:

api:
  base_url: https://au.zaita.com   # or https://<bridge-host>
  version: v1
  timeout_seconds: 30
  verify_tls: true
  retries: 3
  retry_backoff: 60

auth — the Courier credentials or federation configuration. See Authentication for all options and their YAML syntax.

certificate — the certificate attributes and output settings:

certificate:
  output_dir: /etc/ssl/zaita
  cert_filename: certificate
  key_filename: private_key
  generate_keys_locally: true
  key_algorithm: ecdsa
  key_size: 384
  digest: sha-384
  certificate_validity_period: 90
  renewal_threshold_days: 30
  common_name: "service.example.com"
  on_success: "/bin/bash /opt/scripts/restart-service.sh"
  on_failure: "/bin/bash /opt/scripts/alert-on-failure.sh"

logging — recommended for production:

logging:
  level: info
  file: /var/log/zaita-courier.log

Step 4 — Validate the Configuration¶

Before scheduling the Courier, validate the configuration file and verify connectivity:

# Check for configuration errors
zaita-courier validate-config -c /etc/zaita/courier/config.yaml

# Verify the SaaS endpoint (or Bridge) is reachable
zaita-courier check-api-health -c /etc/zaita/courier/config.yaml

# Verify authentication is working
zaita-courier check-api-auth -c /etc/zaita/courier/config.yaml

A successful check-api-auth response confirms the Courier record is correctly configured and lists the domains the Courier has permission to request certificates for.

Step 5 — Schedule the Courier¶

Linux — cron¶

Add a cron entry to run the Courier every 12 hours under the dedicated service account:

sudo crontab -u zaita-courier -e

Add the following line:

0 */12 * * * /usr/bin/zaita-courier generate -c /etc/zaita/courier/config.yaml

Windows — Scheduled Task¶

Create a Scheduled Task to run the Courier every 12 hours:

Open Task Scheduler and select Create Task.
Set the task to run under the gMSA account.
Add a trigger: Daily, repeat every 12 hours.
Add an action: Start a program
- Program: C:\Program Files\Zaita\Courier\courier.exe
- Arguments: generate -c "C:\Program Files\Zaita\Courier\config.yaml"
Ensure Run whether user is logged on or not is selected.
Save the task.

Step 6 — Run the Courier Manually¶

Run the Courier once manually to confirm the full workflow — key generation, CSR submission, certificate issuance, and on_success execution:

zaita-courier generate -c /etc/zaita/courier/config.yaml

Check the output and log file for errors. Verify the certificate and key files are written to the configured output_dir.

Once confirmed, the scheduled task or cron job will handle all subsequent runs automatically.

Managing an Existing Courier¶

Navigate to CLM → Couriers and select the Courier record to:

Update the name, description, owner, or contact email
Enable or disable the Courier (disabling immediately rejects all future authentication attempts)
Add or remove allowed domain patterns
Regenerate the client secret (for Client ID / Secret authentication)
Update the client certificate (for PKI Certificate authentication)
Delete the Courier