Courier Authentication

Each Courier authenticates against the Zaita platform using credentials configured in its Courier record (created under CLM → Couriers). The Courier record controls which domains the Courier can request certificates for and which authentication method it uses.

Seven authentication methods are supported, grouped into credential-less (federated) and credential-based (legacy) options. Federated identity is strongly recommended — it eliminates static credentials and leverages your existing identity infrastructure. Legacy methods can be disabled at the organisation level under Admin → Security Settings if they are not in use.

---

SPIFFE / SPIRE

SPIFFE (Secure Production Identity Framework for Everyone) is an open standard for workload identity. SPIRE is its reference implementation. When a SPIRE agent is deployed alongside your workload, it issues short-lived, automatically rotated identity documents that the Courier can present to the platform for authentication.

This method requires no credentials to be stored anywhere. The Courier receives its identity from the local SPIRE agent's workload API socket at runtime.

YAML configuration:

api:
  uuid: "your-courier-uuid"   # UUID is set here for SPIFFE, not in the auth block

auth:
  method: spiffe
  workload_api_socket: unix:///tmp/spire-agent/public/api.sock

Field	Description
api.uuid	The Courier's UUID. Set in the api section — there is no uuid field in the spiffe auth block.
workload_api_socket	Path to the SPIRE agent's workload API Unix socket.

Ensure the user account running the Courier has read access to the workload API socket. The socket path may differ depending on your SPIRE deployment configuration.

Note: An optional environment variable override is available: set SPIFFE_SVID_PATH to specify the path to the SVID file directly.

---

Azure Workload Identity

Azure Workload Identity provides credential-less authentication for workloads running on Azure or on Azure Arc-enabled on-premises servers. Two variants are available depending on your environment.

Azure — Cloud (Managed Identity / Workload Identity)

For workloads running on Azure (virtual machines, AKS pods, App Service, etc.) with a managed identity or workload identity configured:

YAML configuration:

api:
  uuid: "your-courier-uuid"   # UUID is set here for azure_jwt, not in the auth block

auth:
  method: azure_jwt
  tenant_id: your-azure-tenant-id
  client_id: your-managed-identity-client-id
  token_file: /var/run/secrets/azure/tokens/azure-identity-token  # optional

Field	Description
api.uuid	The Courier's UUID. Set in the api section — there is no uuid field in the azure_jwt auth block.
tenant_id	The Azure Active Directory tenant ID.
client_id	The client ID of the managed identity or app registration.
token_file	(Optional) Override path to the projected token file. Defaults to the AZURE_FEDERATED_TOKEN_FILE environment variable, then /var/run/secrets/azure/tokens/azure-identity-token.

---

Azure Arc — On-Premises (HIMDS)

For on-premises servers enrolled in Azure Arc, use the azure_arc method. The Arc agent provides a local Hybrid Instance Metadata Service (HIMDS) endpoint. The Courier performs a two-step challenge flow against the HIMDS to obtain a token, proving it has local machine access without storing any credentials.

YAML configuration:

auth:
  method: azure_arc
  uuid: "your-courier-uuid"
  resource: "https://management.azure.com/"  # optional
  himds_port: 40342                           # optional

Field	Required	Description
uuid	Yes	The Courier's UUID.
resource	No	Azure resource URI (audience) for the token request. Defaults to https://management.azure.com/.
himds_port	No	Local HIMDS port. Defaults to 40342.

How the HIMDS challenge flow works:

1. The Courier contacts http://localhost:{himds_port}/metadata/identity/oauth2/token.
2. The HIMDS returns HTTP 401 with a WWW-Authenticate header containing a challenge file path.
3. The Courier reads the challenge file from the local filesystem (proving machine-local access).
4. The request is repeated with the challenge file contents as the Authorization header.
5. The HIMDS returns an access token, which the Courier exchanges with the Zaita platform.

Challenge file locations: - Linux: /var/opt/azcmagent/tokens/ - Windows: %ProgramData%\AzureConnectedMachineAgent\Tokens\

The server must be enrolled in Azure Arc and the Arc agent must be running. Assign a managed identity to the Arc-enabled server in the Azure portal.

In the Zaita platform, configure the machine account to accept Azure tokens from the specified tenant and resource.

---

AWS IAM OIDC

AWS IAM OIDC authentication allows workloads running on AWS — or on-premises servers using IAM Roles Anywhere — to authenticate without static credentials. The Courier presents an IAM identity token to the platform.

YAML configuration:

api:
  uuid: "your-courier-uuid"   # UUID is set here for aws_oidc, not in the auth block

auth:
  method: aws_oidc
  role_arn: arn:aws:iam::123456789012:role/ZaitaCourierRole
  region: ap-southeast-2

Field	Required	Description
api.uuid	Yes	The Courier's UUID. Set in the api section — there is no uuid field in the aws_oidc auth block.
role_arn	Yes	The ARN of the IAM role. Sent in the auth payload for the platform to validate.
region	Yes	AWS region.

The token is read from the AWS_WEB_IDENTITY_TOKEN_FILE environment variable path, defaulting to /var/run/secrets/eks.amazonaws.com/serviceaccount/token.

The IAM role must have a trust policy that permits the workload's identity (EC2 instance profile, ECS task role, or EKS service account) to assume it. For on-premises servers using IAM Roles Anywhere, ensure the server's certificate is issued by a trust anchor registered in AWS.

---

Generic OIDC JWT

The oidc_jwt method authenticates using a JWT obtained from any configurable HTTP token endpoint. This is useful for custom identity providers, internal token services, or environments that issue OIDC-compatible tokens but are not covered by the cloud-provider-specific methods above.

YAML configuration:

auth:
  method: oidc_jwt
  uuid: "your-courier-uuid"
  token_endpoint: "https://your-idp.example.com/token"
  resource: "api://zaita-courier"   # optional
  client_id: "courier-client"       # optional

Field	Required	Description
uuid	Yes	The Courier's UUID.
token_endpoint	Yes	URL from which to fetch a JWT. The Courier makes a GET request with resource and client_id as query parameters (if configured).
resource	No	Audience or resource value to include in the token request.
client_id	No	Client ID to include in the token request.

The Courier parses the response as {"access_token": "...", ...} and presents the token to the platform.

---

X.509 Certificate (Legacy)

X.509 certificate authentication uses a client certificate associated with the machine account in the Zaita platform. The certificate is presented via TLS proxy headers during authentication — the private key is not transmitted.

This method involves storing a certificate and private key on the host. Ensure the key file has restricted permissions and is accessible only to the Courier process user.

Note: X.509 certificate authentication can be disabled for your organisation under Admin → Settings. Disable it if your organisation does not use this method.

YAML configuration:

auth:
  method: certificate
  uuid: "your-courier-uuid"
  cert_path: /etc/zaita/courier/client.crt
  key_path: /etc/zaita/courier/client.key

Field	Required	Description
uuid	Yes	The Courier's UUID.
cert_path	Yes	Path to the PEM-encoded client certificate.
key_path	Yes	Path to the PEM-encoded private key for the client certificate.

---

Client ID / Secret (Legacy)

Client ID and secret is a traditional credential-based authentication method. It is the least secure option, as it requires storing credentials on the host in a location accessible to the Courier.

This method is suitable only for low-sensitivity environments or development deployments where no federated identity provider is available. It should not be used in production environments where credential-less alternatives are available.

Note: Client ID and secret authentication can be disabled for your organisation under Admin → Settings. Disable it if your organisation does not use this method.

YAML configuration:

auth:
  method: client_secret
  uuid: "your-courier-uuid"
  client_id: cour_your_client_id
  client_secret: your_client_secret

Credentials can also be provided via environment variables referenced in the YAML file, which avoids storing plaintext secrets in configuration files:

auth:
  method: client_secret
  uuid: "your-courier-uuid"
  client_id: ${ZAITA_CLIENT_ID}
  client_secret: ${ZAITA_CLIENT_SECRET}

Field	Required	Description
uuid	Yes	The Courier's UUID.
client_id	Yes	The machine account client ID (cour_-prefixed).
client_secret	Yes	The machine account secret. Shown only once at creation time.

---

Authentication Failure Hook

Every auth block accepts an optional on_failure field — a shell command to run if authentication fails before the process exits. Use this to trigger alerts or remediation when a Courier cannot authenticate:

auth:
  method: client_secret
  uuid: "your-courier-uuid"
  client_id: cour_your_client_id
  client_secret: your_client_secret
  on_failure: "/usr/local/bin/alert_auth_failure.sh"

The hook is executed via sh -c on Unix or cmd /C on Windows. A non-zero exit code from the hook is logged as a warning and does not change the Courier's own exit code.

---

UUID Field Reference

The Courier UUID is sent to the platform as part of every authentication request. Where the UUID is placed in the YAML config depends on the auth method:

Method	UUID field location
client_secret	auth.uuid
certificate	auth.uuid
azure_arc	auth.uuid
oidc_jwt	auth.uuid
azure_jwt	api.uuid
aws_oidc	api.uuid
spiffe	api.uuid

---

Disabling Legacy Authentication Methods

Organisations that do not use X.509 certificate or Client ID/Secret authentication can disable these methods globally to reduce attack surface:

1. Navigate to Admin → Settings in the web portal.
2. Under Security, disable X.509 Certificate Authentication and/or Client ID/Secret Authentication as appropriate.

Once disabled, any Courier attempting to use that method will be rejected at authentication.