Skip to main content
2 video tutorials

Policies & approvals

Two governance gates: a project-scoped certificate policy that constrains every new issuance (key types, allowed issuers, SAN globs, naming regex, auto-renew requirement — existing certificates and their renewals are grandfathered), and a request / approve / reject workflow that interposes a human review on sensitive operations.

Certificate policy​

One policy per project (singleton — you don't stack policies). Enforcement is synchronous and applies to new issuance only: the request fails with HTTP 422 and a structured violation list before any work is queued. Renewals and reissues of existing certificates are never policy-checked — a policy tightened after issuance does not break certificates already in service. The policy is cached for 60 seconds; saves take up to that long to propagate to all workers.

An empty policy (or no policy) means no enforcement.

Rules​

RulePurposeEmpty value
allowed_key_typesWhitelist of key types: ECDSA-P256, ECDSA-P384, RSA-2048, RSA-3072, RSA-4096. Up to 10 entries.All allowed.
allowed_issuer_typesWhitelist of issuer types (acme / msca / ca_connector).All allowed.
allowed_issuer_idsWhitelist of specific ACME-account / MSCA-connection / CA-connection IDs (subject to the type list).All allowed.
san_rules.allowed_patternsGlobs — a SAN matching any allow glob passes.Allow-by-default.
san_rules.deny_patternsGlobs — a SAN matching any deny glob is rejected. Evaluated before allow.Deny none.
san_rules.max_san_countCap on number of SANs per cert.No cap.
naming_patternGo regex; the certificate's human-assigned name must match.No check.
require_auto_renewRejects certs with auto_renew: false.Manual renewals allowed.

Evaluation order​

  1. Resolve the policy for the project (cached, 60 s TTL).
  2. Key type — reject on mismatch.
  3. Issuer type, then issuer ID — reject on mismatch.
  4. SAN rules: max_san_count, then deny globs, then allow globs (if an allow list is set, a SAN not matching any allow is rejected).
  5. Naming regex — reject if the certificate name doesn't match.
  6. require_auto_renew.
  7. If any step produced a violation, return HTTP 422 with the full list. The UI surfaces violations inline on the issuance form, with the offending rule named.

Example policy​

allowed_key_types: ["ECDSA-P256", "ECDSA-P384"]
allowed_issuer_types: ["acme", "msca"]
san_rules:
allowed_patterns: ["*.example.com", "*.internal.example.com"]
deny_patterns: ["*.admin.example.com"]
max_san_count: 10
naming_pattern: "^(prod|stage)-[a-z0-9-]+$"
require_auto_renew: true

Reads: ECDSA only, any configured ACME or MSCA issuer, SANs must live under example.com or its internal subtree but never under admin.example.com, up to 10 SANs per cert, the human-readable name must start with prod- or stage-, auto-renew must be on, private-key download is gated only by role (Operator) and, optionally, the download-approval setting.

Configure & live test​

  1. Settings → Certificate Policy (project admin role required).
  2. Toggle Enable policy.
  3. Fill the rules. The form has live-test inputs — type a candidate cert name to verify the naming regex and a candidate domain to verify the SAN allow / deny globs before you save. A naming pattern the browser cannot evaluate shows a hint and is checked on save; the server refuses a pattern Go cannot compile with 400.
  4. Save. Cache TTL means changes take up to 60 s to propagate.

Bypass: there is no in-UI bypass. If a policy blocks a legitimate request at 2 a.m., either temporarily relax the specific rule (admin-only, audit-logged), disable the policy + issue + re-enable, or use a different project. Every disable / relax is audit-logged.

Approval workflow​

An optional gate that interposes a human review on top of RBAC. RBAC controls who can submit; the approval policy controls whether they execute directly or queue a request that must be approved by a reviewer with the right role.

Each project has its own approval policy under Settings → Approvals (with the project selected). For every operation it says which operators need approval: No approval, All operators, or Selected operators (the users listed, plus the members of the user groups listed). Admins and owners are never gated. Only an organization owner can change a project's policy; every project member can read it. A project that never saved a policy uses the defaults: configuration changes need approval from all operators, everything else needs none.

Operations that can be gated:

  • Issue — a new cert request.
  • Renew — manual renewal outside the scheduler.
  • Reissue — key rotation.
  • Revoke — revocation at the CA.
  • Download (key export) — pulling the private key.
  • Configuration changes — operator create/update/delete of targets, target groups (and their members), PathSets, ActionSets, project variables and module configs. All operators by default.
  • Distribution actions — operator link / update / unlink / execute / rollback of a distribution. No approval by default.

The last two gate the deployment supply chain rather than the certificate itself, and only the manual operator action is gated — the scheduler's automatic post-renewal distribution is not, because gating it would block renewals. A gated write answers 202 Accepted carrying an approval request instead of the resource; see Approval workflow → What can be gated.

Request states​

StateMeaning
pending_approvalAwaiting review. (That is the literal value — filtering on pending matches nothing.)
approvedReviewer accepted; the requester now triggers execution explicitly.
executing / executedAction running / ran (success or failure captured on the resulting job).
execution_failedThe approved action failed to execute (retryable for some error codes).
rejectedReviewer declined (an optional reason can be given).
expiredNot reviewed within 7 days.
cancelledRequester cancelled before review.

Submit a request​

  1. Attempt the gated action on the UI (e.g. click Revoke on a cert).
  2. If the project's approval policy gates this operation for you, submitting the action raises an approval request instead of running it (the API answers 202 with the request). There is no requester reason field; acknowledge any preflight warnings.
  3. Submit. The action is queued; the cert detail surface shows the pending request.

An approved issuance request is executed against the issuer the request named — an ACME account, an AD CS connection or a CA connection — with the same job chain as a direct issuance.

Preflight warnings are raised for AD CS (MSCA) issuance only — a stale template cache, a connection not validated in the last 24 hours, or credentials changed since the last successful authentication. Other issuer types skip preflight entirely, so a revoke or renew request carries no blast-radius analysis: an approver reviewing one is not being shown which distributions it would affect. Where a warning does apply, acknowledging it is not optional and the acknowledgement is recorded in the audit trail.

Review a request​

  1. Reviewer opens My Requests → Reviews — every pending request they are empowered to act on.
  2. Click a row; the full context appears (requester, reason, preflight warnings, target cert, action).
  3. Approve, or Reject with an optional reason.
  4. On approve, the requester triggers execution explicitly with the Execute button on My Requests. The requester is notified via their configured channels.

Who can approve what​

  • Reviewers need project admin (or org admin/owner) on the request's project.
  • Self-approval is blocked — the approver cannot be the requester.
  • Admins and owners bypass the gate — their gated operations run directly and an auto-executed approval record is written for the audit trail; no request waits for a second person.

TTL & expiry​

Requests time out after a fixed 7-day TTL (evaluated lazily when the request is next read). An expired request terminates in expired; the action does NOT execute. The requester can re-submit.

Notifications​

  • approval.requested — fires when a new request enters pending. Route this to a reviewer channel (shared inbox, Slack group).
  • approval.approved / approval.rejected — fires on state transition. Route back to the requester.
  • approval.executed / approval.expired — execution completed / request timed out.

Full lifecycle, execute/retry semantics, and download tokens: Approval workflow.

  • approval.expired — catches stale requests; useful for metrics.

Configure under Notifications with the same channel + rule pattern as cert events.

Troubleshooting​

"Policy violation" but no rule seems to apply​

Check the cached age — a recent save may not have propagated yet (60 s TTL). The 422 response names the exact rule.

Naming regex silently rejects everything​

Usually a Go-regex-syntax issue (PCRE features like lookaheads aren't supported). The save returns the server's compile error; the browser-side live test cannot evaluate such patterns and says so.

Nobody can approve my request​

There is no laddered approver model and no "no eligible reviewer" error. A request is reviewable by any project admin (and by org admins and owners). If a request is sitting unactioned, the project simply has no admin — grant one, or have an admin perform the action directly, since admin/owner actions bypass the gate.

Request stuck in approved, action didn't fire​

The executing worker is down or the action failed with a system error. Check Jobs — the approval-triggered job carries the approval ID in its payload.

See also​

Video tutorials

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Approvals for Issuing, Revoking and Private-Key DownloadsYouTube ↗
Approvals for Certificate Deployments (Four-Eyes Principle)YouTube ↗