Skip to content

Best Practices for Couriers

Scheduling

Match your schedule to your rotation frequency. If secrets are rotated every 90 days, a daily Courier run is sufficient. If secrets may be rotated at any time in response to a security event, run the Courier more frequently — every 15 minutes is a reasonable baseline.

Do not run too infrequently. A Courier that runs once a week will leave consuming applications running on stale credentials for up to a week after a rotation.

Use a dedicated service account for the cron job. The user running the Courier should have read access to the Courier configuration file and write access to the secrets output directory — nothing more.

File Permissions

Write secrets to a dedicated directory. Use a directory owned by the application user and not readable by other processes — for example, /etc/myapp/secrets/ with mode 0700. The Courier always writes output files with mode 0600, but the parent directory permissions provide an additional layer of containment.

Do not write secrets to world-readable locations. Avoid /tmp, shared log directories, or any path readable by users other than the consuming application.

Hooks

Always configure on_failure. A Courier failure may indicate a connectivity problem, a revoked access grant, or a key rotation issue. Configure on_failure to send an alert so failures are investigated promptly rather than silently leaving applications running on stale or absent credentials.

on_failure: "curl -s -X POST https://alerting.example.com/webhook -d '{\"alert\":\"courier-failed\"}'"

Use on_success to reload services. If your application loads secrets at startup, configure on_success to trigger a reload after the secrets file is updated. This ensures the application picks up new credentials without a manual restart.

on_success: "systemctl reload myapp"

Authentication

Prefer credential-less authentication methods. Couriers support SPIFFE/SPIRE, Azure Workload Identity, Azure Arc, AWS IAM OIDC, and generic OIDC JWT authentication. These eliminate static credentials and remove the risk of the Courier's own credentials being exposed. Use client_id / client_secret only in environments where federated identity is unavailable.

See CLM Couriers — Authentication for configuration details.

Network Design

Route Couriers through a Bridge in on-premises environments. Rather than granting each host running a Courier direct outbound internet access, configure Couriers to connect through a local Bridge. The Bridge acts as a single controlled egress point for all Courier traffic.

Always verify TLS. Do not disable TLS certificate verification in Courier configuration. The platform's certificate is issued by a well-known CA and should always be validated.

Next Steps