[1.18] Add workflow history signing documentation by JoshVanL · Pull Request #5082 · dapr/docs

JoshVanL · 2026-03-20T17:53:35Z

Add documentation for the workflow history signing feature, which provides cryptographic tamper detection for workflow execution histories using the sidecar's mTLS X.509 SPIFFE identity.

Implemented in dapr/dapr#9778

Add documentation for the workflow history signing feature, which provides cryptographic tamper detection for workflow execution histories using the sidecar's mTLS X.509 SPIFFE identity. Implemented in dapr/dapr#9666 Signed-off-by: joshvanl <me@joshvanl.dev>

Signed-off-by: joshvanl <me@joshvanl.dev>

Copilot

Pull request overview

Adds documentation for the “workflow history signing” feature, explaining how Dapr workflows sign and verify workflow history using the sidecar’s mTLS X.509 identity, and surfaces operational guidance around certificate/CA rotation.

Changes:

Adds a new concept doc detailing workflow history signing, verification, failure modes, and state layout.
Links the new doc from the workflow overview and the preview features list.
Adds mTLS certificate rotation warnings specific to signed workflow history.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

File	Description
daprdocs/content/en/operations/support/support-preview-features.md	Adds “Workflow History Signing” to the preview features table and links to the new doc.
daprdocs/content/en/operations/security/mtls.md	Adds warnings about CA rotation impact on signed workflow histories.
daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md	Adds a “History signing” overview section linking to the detailed doc.
daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-history-signing.md	New, comprehensive documentation page for workflow history signing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: joshvanl <me@joshvanl.dev>

Add coverage for the v1.18 follow-up PRs on top of #9778: - dapr/dapr#9825 Tamper response: instead of just deleting reminders, the orchestrator now appends a single unsigned terminal ExecutionCompleted event tagged DAPR_WORKFLOW_HISTORY_TAMPERED on in-flight workflows, leaves already-completed workflows untouched, and routes signing-configuration mismatches through a separate ConfigurationError path that does not invoke tamper recovery. - dapr/dapr#9831 Child workflow and activity attestation: cross-identity completion events now carry a signed ChildCompletionAttestation / ActivityCompletionAttestation that commits to parent instance id, parent task scheduled id, a canonical ioDigest, the signer cert digest, and terminal status; receivers verify before the event enters the inbox and absorb foreign certs into ext-sigcert-NNNNNN. - dapr/dapr#9890 Lineage propagation: each PropagatedHistoryChunk now carries its own producer-signed signature plus DER cert chain; receivers verify chain-of-trust, SPIFFE app match, contiguity, and reject malformed variants explicitly. Also expand the failure-causes table, the state-store layout, the verification flow diagram, and the security-properties table. Signed-off-by: joshvanl <me@joshvanl.dev>

marcduiker

LGTM

Signed-off-by: Marc Duiker <marcduiker@users.noreply.github.com>

marcduiker

LGTM, thanks for adding all the diagrams!

msfussell

Love the details on this article Thank you. Mostly my feedback in on the operational guidance side how to manage Dapr's default root cert when there are long running workflows that you would not be able to purge.

msfussell · 2026-05-26T22:57:11Z

+
+Dapr workflow history signing provides cryptographic tamper detection for
+workflow execution histories. Every history event produced during a workflow's
+lifetime is signed using the sidecar's mTLS identity (X.509 SVID), creating an


Suggested change

lifetime is signed using the sidecar's mTLS identity (X.509 SVID), creating an

lifetime is signed using the sidecar's mTLS identity (X.509 SPIFFE Verifiable Identity Document (SVID)), creating an

msfussell · 2026-05-26T22:59:04Z

+1. Deterministically marshals each new history event.
+2. Computes a SHA-256 digest over the batch of events.
+3. Chains the new digest to the previous signature's digest.
+4. Signs the combined input using the sidecar's [SPIFFE](https://spiffe.io/) X.509 private key.


Suggested change

4. Signs the combined input using the sidecar's [SPIFFE](https://spiffe.io/) X.509 private key.

4. Signs the combined input using the sidecar's [SPIFFE](https://spiffe.io/) X.509 private key (SVID)

msfussell · 2026-05-26T23:03:07Z

+
+| Condition | How to check |
+|-----------|-------------|
+| mTLS is enabled | Sentry is running and the sidecar has a valid SVID |


msfussell · 2026-05-26T23:57:20Z

+### Does signing add latency to workflow execution?
+
+The signing operation (SHA-256 hashing and ECDSA/Ed25519 signing) is fast and
+adds negligible latency. The main cost is the additional state store writes for


So does it add latency due to the writes? Not sure you answered the question.

Yes, however is negligible compared to the existing latency profile. Expanded

msfussell · 2026-05-27T00:06:38Z

 If you signed the new cert root with a **different private key**, you must restart the Dapr Sentry service, followed by the remainder of the Dapr control plane service.

+{{% alert title="Workflow history signing" color="warning" %}}
+If you rotate to a completely new root CA (different private key), any running workflows with [signed history]({{% ref "workflow-history-signing.md" %}}) will fail signature verification because their signing certificates were issued by the old CA. Those workflows will be reported as FAILED with error type `SignatureVerificationFailed`. To avoid this, complete or purge in-flight workflows before performing a full CA rotation.


This last sentence needs to be more discoverable in the FAQ above and in the overall article.
Is there anyway that you could overlap these root certs, so that you do not have to have downtime in affect? Say that your workflows run for 3 weeks on average, how to you purge these and update the root cert? That would seem to be a quite difficult task. Can you provide guidance here?

msfussell · 2026-05-27T00:07:19Z

 *Note: If you signed the cert root with a different private key, restart the Dapr instances.*

+{{% alert title="Workflow history signing" color="warning" %}}
+If you rotate to a completely new root CA (different private key), any running workflows with [signed history]({{% ref "workflow-history-signing.md" %}}) will fail signature verification. Complete or purge in-flight workflows before performing a full CA rotation.


Same here. Needs specific guidance for long running workflows.

Signed-off-by: joshvanl <me@joshvanl.dev>

JoshVanL · 2026-05-27T10:52:27Z

Thanks @msfussell, please can you take another look?

Signed-off-by: joshvanl <me@joshvanl.dev>

msfussell

LGTM

JoshVanL requested review from a team as code owners March 20, 2026 17:53

Copilot AI review requested due to automatic review settings March 20, 2026 17:53

Copilot started reviewing on behalf of JoshVanL March 20, 2026 17:54 View session

Adds mermaid shortcode

7c0dbf6

Signed-off-by: joshvanl <me@joshvanl.dev>

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Review comments

1dc1292

Signed-off-by: joshvanl <me@joshvanl.dev>

JoshVanL changed the title ~~Add workflow history signing documentation~~ [1.18] Add workflow history signing documentation Mar 22, 2026

Update history signing docs based on implementation

b860f68

Signed-off-by: joshvanl <me@joshvanl.dev>

This was referenced Apr 14, 2026

v1.18.0 Release Planning dapr/dapr#9642

Closed

REQUEST: Maintainer role for @JoshVanL in dapr/docs dapr/community#708

Closed

JoshVanL and others added 4 commits April 23, 2026 10:06

Update feature gate name

616047e

Signed-off-by: joshvanl <me@joshvanl.dev>

Use correct version for supported feature

daedf4a

Signed-off-by: joshvanl <me@joshvanl.dev>

Merge branch 'v1.18' into workflow-history-signing

236bd01

marcduiker approved these changes May 25, 2026

View reviewed changes

Merge branch 'v1.18' into workflow-history-signing

14480ca

Signed-off-by: Marc Duiker <marcduiker@users.noreply.github.com>

marcduiker approved these changes May 26, 2026

View reviewed changes

msfussell reviewed May 27, 2026

View reviewed changes

Merge branch 'v1.18' into workflow-history-signing

d4b2e0f

msfussell mentioned this pull request May 27, 2026

workflow history propagation docs #5153

Merged

msfussell assigned JoshVanL May 27, 2026

msfussell added this to the v1.18 milestone May 27, 2026

Review comments

316b835

Signed-off-by: joshvanl <me@joshvanl.dev>

JoshVanL added 2 commits May 27, 2026 18:53

More notes on root CA lifecycle

77b183e

Signed-off-by: joshvanl <me@joshvanl.dev>

Merge branch 'v1.18' into workflow-history-signing

bad3ae6

JoshVanL mentioned this pull request May 27, 2026

dapr init: option to run Sentry in self-hosted mode dapr/cli#1648

Open

4 tasks

msfussell approved these changes May 29, 2026

View reviewed changes

Merge branch 'v1.18' into workflow-history-signing

a6baf46

marcduiker merged commit ea2c412 into dapr:v1.18 Jun 1, 2026
4 checks passed

	lifetime is signed using the sidecar's mTLS identity (X.509 SVID), creating an
	lifetime is signed using the sidecar's mTLS identity (X.509 SPIFFE Verifiable Identity Document (SVID)), creating an

	4. Signs the combined input using the sidecar's [SPIFFE](https://spiffe.io/) X.509 private key.
	4. Signs the combined input using the sidecar's [SPIFFE](https://spiffe.io/) X.509 private key (SVID)

	\| mTLS is enabled \| Sentry is running and the sidecar has a valid SVID \|
	\| mTLS is enabled \| Sentry service is running and the sidecar has a valid SVID \|

Uh oh!

Conversation

JoshVanL commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcduiker left a comment

Choose a reason for hiding this comment

Uh oh!

marcduiker left a comment

Choose a reason for hiding this comment

Uh oh!

msfussell left a comment

Choose a reason for hiding this comment

Uh oh!

msfussell May 26, 2026

Choose a reason for hiding this comment

Uh oh!

msfussell May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

msfussell May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

msfussell May 26, 2026

Choose a reason for hiding this comment

Uh oh!

JoshVanL May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msfussell May 27, 2026

Choose a reason for hiding this comment

Uh oh!

msfussell May 27, 2026

Choose a reason for hiding this comment

Uh oh!

JoshVanL commented May 27, 2026

Uh oh!

msfussell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

JoshVanL commented Mar 20, 2026 •

edited

Loading