Configuration Reference

Documentation for the image tag 1.0.0-rc1. See Versions for the documentation of a release.

Configuration Reference

Configuration is read from environment variables. In .NET, a nested setting such as Identity:StepUp:Enabled is written with double underscores: Identity__StepUp__Enabled.

Ports

Service	Container port	Purpose
Web UI	8080	Browsers
Identity	8081	OIDC sign-in
API	8082	REST API, CRL, OCSP, qca
ACME	8083	/acme/directory
EST	8084	/.well-known/est/* (multi container only, always HTTPS)

The published host port must equal the container port (or the matching *_PORT variable must be set to the published one), because Qertum advertises these numbers.

Common variables

Variable	Default	Meaning
QERTUM_HOST	localhost	Name or IP clients use to reach Qertum. Set it. Never localhost for multi container
IdentityService__SeedAdminPassword	password	Password of the admin user created on first start. Read only while the identity store is empty. When left at the default, the first login must change it. Multi container calls this SEED_ADMIN_PASSWORD
QERTUM_API_INTROSPECTION_SECRET	generated	Secret of the internal qertum-api client. Leave unset to generate and persist one on /data
WEB_PORT, IDENTITY_PORT, API_PORT, ACME_PORT, EST_PORT	8080–8084	Advertised ports
ASPNETCORE_ENVIRONMENT	Production	Keeps API reference pages and health endpoints off

Identity and sign-in

Variable	Default	Meaning
Identity__Authority	set by the image	Issuer URL the API trusts. Must equal the token's iss exactly, including any path (Keycloak: https://host/realms/<realm>)
Identity__Audience	qertum-api	Required aud value
Identity__RequireHttpsMetadata	false (single container, plain HTTP)	Set true once the authority is HTTPS
Identity__StepUp__Enabled	false	Require a recent second factor for the most sensitive operations. Needs an external provider that emits acr and auth_time
Identity__StepUp__AcrValues	mfa	Accepted acr values, comma separated, case sensitive
Identity__StepUp__MaxAgeSeconds	300	Maximum age of auth_time (1 to 86400)
IdentityService__SecretStorageProvider	unset	LocalFileKey or LocalTpm for the identity service's own certificates
IdentityService__CertificateLifetimeDays	1825	Validity of newly created identity signing certificates
IdentityService__CertificateRenewBeforeDays	90	How far ahead of expiry a replacement is created. Keep it longer than your longest refresh-token lifetime
IdentityService__DisableTransportSecurity	true (plain HTTP deployments)	Lets the identity service run over HTTP. Set false once the issuer is HTTPS
OpenIdConnect__RequireHttpsMetadata	false (plain HTTP)	Same switch for the web UI's sign-in

Optional features

Variable	Default	Meaning
Approvals__GrantWindowMinutes	15 (1–1440)	How long a second administrator's approval stays usable
Approvals__RequestTtlHours	24 (1–168)	How long an approval request stays open
Approvals__RetentionDays	365 (1–3650)	How long approval records are kept
Notices__ExpiryDays	30,14,7,1	Days before expiry at which a notice is raised
Acme__Dns01__Resolvers	system resolvers	Resolvers used for dns-01 validation
AuditLog__Checkpoint__IntervalMinutes	60	How often the audit checkpoint webhook event is sent
OTEL_EXPORTER_OTLP_ENDPOINT	unset	Where to export OpenTelemetry metrics and traces. Nothing leaves the process while unset

Two-person approval itself is switched on in the web UI under Settings, Issuance, not by a variable. Turning it on means that with a single administrator, the operations it gates cannot be done until it is switched off again.

Webhook destinations

Webhooks may reach public HTTP(S) receivers by default. Private, loopback, link-local and cloud-metadata addresses are blocked unless an administrator adds an exact rule on the Webhooks page or with qca webhooks destinations add. Plan these rules before relying on webhooks to internal receivers.

Rate limits

The API limits requests under /v1/certificate-requests with RateLimiting__PermitLimit (100), RateLimiting__WindowSeconds (60) and RateLimiting__QueueLimit (10). Clients over the limit receive 429.

Monitoring

Services publish OpenTelemetry metrics when OTEL_EXPORTER_OTLP_ENDPOINT is set. The signals worth alerting on:

Metric	Alert when
ca.crl.age	Above 75 % of the CRL validity; page at 100 %
ca.background_job.failures	Any outcome=failed
ca.certificates.expiring	Above 0 for longer than your renewal lead time
ca.certificate.issue_errors	Above 0 for 10 minutes
ca.queue.depth	Above 0 while ca.certificate.issued_total does not move
ca.webhook.deliveries	outcome=failed above 0

The gauges are reported by the queue consumer only, so also alert when the metric disappears.