Certificate Templates¶

Designing Project Certificate Templates — Every Parameter Explained

Document Version: 1.0.0
Last Updated: 2026-06-30

1. Two Template Systems¶

MazeVault exposes two distinct, complementary template systems. Understanding the difference is essential — they live in different places and serve different purposes.

System	Where	Purpose
Configuration templates	Certificates → Templates (organization-wide PKI catalogue)	Reusable, organization-level certificate profiles bound directly to a CA. Used when requesting a certificate ad hoc.
Project templates	Project → Settings → Templates	Templates scoped to a single project. A project template has a category (`secrets`, `certificates`, or `keys`) and a subtype. A project template of category certificates drives certificate issuance for that project.

graph TD
    A["Project Template<br/>category = certificates"] -->|"protocol_config.certificate_template_id"| B["Certificate Template<br/>(subordinate record)"]
    B --> C["Issuance Engine<br/>(SignCSR)"]
    C --> D["Issued X.509 Certificate"]

    classDef proj fill:#EBF5FB,stroke:#2196F3,stroke-width:2px,color:#1565C0
    classDef cert fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px,color:#2E7D32
    class A proj
    class B,C,D cert

When you create a project template of category certificates, MazeVault creates a subordinate certificate template behind the scenes and links it through protocol_config.certificate_template_id. The fields documented here are the protocol_config keys of that project template; they are unmarshalled into the subordinate certificate template that the issuance engine consumes.

2. Where the Subject Comes From¶

A certificate's Subject (Common Name, Organization, OU, Email, Locality, State, Country) and its Subject Alternative Names are not fixed on the Certificate Settings step. They are driven by the template Variables step.

On the Variables step you define variables such as COMMON_NAME, ORGANIZATION, ORGANIZATIONAL_UNIT, EMAIL, LOCALITY, STATE, COUNTRY, and SAN_DNS. These are resolved per request, which keeps a single template reusable across many concrete certificates. The Certificate Settings step therefore configures issuance policy and cryptographic parameters only — never literal subject values.

The single subject-related toggle that does live on Certificate Settings is Add Common Name to SAN (add_cn_to_san), because it controls SAN behavior, not a subject value.

3. Certificate Settings — Parameter Reference¶

The Certificate Settings step is organized into outlined cards. Every field maps to a protocol_config key. The Where applied column states when the value takes effect:

Issued certificate — the value is written into the issued X.509 certificate.
Validation / gating — the value constrains or gates requests but is not written into the certificate.
CSR generation — the value is a default used only when MazeVault generates the key pair and CSR (it does not override a customer-supplied CSR).
Rotation — the value governs automated renewal/rotation.
Routing — the value selects the issuing authority.

Identity & Intent¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`code`	Template Code	string	derived from name	unique per org	Metadata	`web-server-tls`
`cert_type`	Certificate Type	enum	`""` (Auto)	one of the catalogue values, or empty to derive from the subtype	Metadata / issuance intent	`ssl_tls`

Issuing CA¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`ca_account_id`	CA Account	uuid	none	must reference a configured CA account	Routing	`550e8400-…`
`ca_product_id`	CA Product	uuid	none	requires a CA account	Routing	`550e8400-…`
`signature_algorithm`	Signature Algorithm	enum	`""` (CA default)	mirrors Go `x509.SignatureAlgorithm` names	Issued certificate	`SHA256WithRSA`

Key & Algorithm¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`key_algorithm`	Key Algorithm	enum	`RSA`	`RSA`, `ECDSA`, `Ed25519`	CSR generation	`ECDSA`
`key_size`	Default Key Size	integer	`2048`	valid size for the algorithm (RSA: 2048/3072/4096; ECDSA: 256/384/521; Ed25519: 256)	CSR generation	`3072`
`allowed_key_sizes`	Allowed Key Sizes	integer[]	`[]` (any)	subset of valid sizes for the algorithm	Validation / gating (enforced at issuance)	`[2048, 4096]`

Allowed Key Sizes is enforced at signing

When allowed_key_sizes is non-empty, the issuance engine rejects any CSR whose public-key bit length is not in the list — including externally supplied CSRs — before the certificate is created. An empty list means any size valid for the algorithm is accepted.

Validity¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`validity_days`	Validity (Days)	integer	`365`	> 0	Issued certificate (`NotAfter = NotBefore + validity_days`)	`90`
`min_validity_days`	Min Validity (Days)	integer	`30`	≤ `max_validity_days`	Validation / gating	`30`
`max_validity_days`	Max Validity (Days)	integer	`825`	≥ `min_validity_days`	Validation / gating	`825`

Key Usage & Extended Key Usage¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`key_usage`	Key Usage	string[]	`[]`	subset of the 9 RFC 5280 §4.2.1.3 bits	Issued certificate	`["digitalSignature","keyEncipherment"]`
`extended_key_usage`	Extended Key Usage	string[]	`[]`	subset of the 6 supported EKU OIDs	Issued certificate	`["serverAuth","clientAuth"]`
`add_cn_to_san`	Add CN to SAN	boolean	`true`	—	CSR generation (SAN behavior)	`true`

Key Usage values: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly.

Extended Key Usage values: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, ocspSigning.

CA Constraints & Policies¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`is_ca`	Issue as CA certificate	boolean	`false`	—	Issued certificate (Basic Constraints)	`false`
`max_path_length`	Max Path Length	integer	`0`	only meaningful when `is_ca` is true	Issued certificate (pathLenConstraint)	`0`
`policy_identifiers`	Policy Identifiers	string[]	`[]`	dotted-decimal OIDs	Issued certificate (certificate policies)	`["1.3.6.1.4.1.311.21.10"]`
`certificate_policies`	Certificate Policies	string[]	`[]`	dotted-decimal OIDs	Issued certificate (merged with `policy_identifiers`, deduplicated)	`["2.23.140.1.2.1"]`

CA path length & policy handling

When is_ca is true and max_path_length is 0, the certificate is constrained to pathlen:0 (may issue end-entity certificates but no further CAs). policy_identifiers and certificate_policies are merged and deduplicated; invalid OID strings are skipped with a warning rather than aborting issuance.

Renewal & Rotation¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`auto_renewal_enabled`	Auto Renewal	boolean	`true`	—	Rotation	`true`
`renewal_days_before_expiry`	Renewal Days Before Expiry	integer	`30`	> 0	Rotation	`30`
`renewal_key_policy`	Key Policy on Renewal	enum	`regenerate`	`regenerate` or `reuse`	Rotation	`regenerate`

Renewal key policy precedence

A template that pins regenerate (generate a new key pair on renewal) overrides a more permissive organization key-reuse policy. reuse keeps the existing private key. When no template value is set, the organization renewal policy applies.

Governance¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`require_approval`	Require approval before issuance	boolean	`false`	—	Validation / gating	`false`

External CA Integration¶

JSON key	UI label	Type	Default	Constraint	Where applied	Example
`external_template_name`	External Template Name	string	`""`	used only with an external CA (e.g. ADCS)	Routing (external CA)	`WebServerV2`
`external_template_oid`	External Template OID	string	`""`	dotted-decimal OID	Routing (external CA)	`1.3.6.1.4.1.311.21.8.1`

4. What Lands in the Issued Certificate¶

For quick reference, here is the disposition of each governed field:

Written into the issued certificate: validity_days, key_usage, extended_key_usage, is_ca, max_path_length, policy_identifiers, certificate_policies, signature_algorithm.
Validation / gating only (not in the certificate): allowed_key_sizes, min_validity_days, max_validity_days, require_approval.
Rotation behavior: auto_renewal_enabled, renewal_days_before_expiry, renewal_key_policy.
CSR-generation defaults only: key_algorithm, key_size, add_cn_to_san. These apply when MazeVault generates the key pair and CSR; they do not override a customer-supplied CSR (except allowed_key_sizes, which is enforced at signing for all CSRs).
Routing / selection: ca_account_id, ca_product_id, external_template_name, external_template_oid.

Certificate Management — requesting, revoking, importing, and exporting certificates.
ACME Certificate Automation — automated issuance via ACME.