Skip to content

Commit 9a9d5a1

Browse files
MNIJCDS\michiel.nijdam
MNIJ
and
CDS\michiel.nijdam
authored
Blog signing integration (#29)
* Blog entry for integrating signing software with ZGW * Changes to title and introduction of blog post * Formatted latest changes --------- Co-authored-by: CDS\michiel.nijdam <[email protected]>
1 parent e054448 commit 9a9d5a1

File tree

4 files changed

+172
-0
lines changed

4 files changed

+172
-0
lines changed

‎blog/2025-03-27-integrating-signing-software-with-zgw.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
slug: integrating-signing-software-with-zgw
3+
title: A standardized way to initiate signing of documents in the ZGW landscape
4+
authors: michielnijdam
5+
tags: [integrations]
6+
---
7+
8+
## Introduction
9+
10+
Digitally signing documents is a common task in the workflow of handling a case. Several software vendors offer solutions for this. This article describes a standardized pattern to handle the signing of documents within the ZGW API landscape. Most API-calls in this pattern are already part of the ZGW standard. The missing link was a way to initiate the signing transaction. In this article we propose a standardized trigger message for this purpose.
11+
12+
<!-- truncate -->
13+
14+
## Signing sequence
15+
16+
The basic flow for signing documents is as follows:
17+
18+
- A user working on a case in a task specific application (TSA) or case management system (ZAC) selects one or more documents related to the case to be signed by one or more signers
19+
- The TSA or ZAC sends a trigger message to the signing software
20+
- The signing software retrieves the documents from the DRC and presents them to the signers
21+
- When all signers have signed the documents, the signing software uploads the signed versions of the documents to the DRC. Depending on the vendor and configuration of the signing software, it might also add a separate evidence document with proof of signing to the case.
22+
- The signing software sends a notification to the NRC to indicate signing is complete
23+
- The TSA or ZAC handles this notification, for instance by informing the user
24+
25+
Below is a sequence diagram with a more detailed view of this flow.
26+
[![Sequence diagram](/img/signing-sequence.png)](/img/signing-sequence.png)
27+
[Use this link to view the diagram in full size.](/img/signing-sequence.png)
28+
29+
## ZGW Compliance
30+
31+
Most API requests in this sequence are standard requests already defined in the ZGW specification, with the following two remarks:
32+
33+
- The ZGW standard does not provide in a way to initiate a signing transaction. This article proposes a standardized format for this trigger message. This is the only non-ZGW request in this sequence.
34+
- The notification to the NRC at the end of the signing flow is a standard request following the NRC specification. The channel used is a custom channel "documentacties". This channel needs to be registered in the NRC for the signing flow to work. This is a one-tima action that should be done by the administrator of the ZGW implementation. Registering a new channel is a standard request within the NRC specification, so all compliant ZGW implementations should support adding this channel. This same channel might be used for other events concerning documents in the future.
35+
36+
## Scope of this article
37+
38+
This article describes the interaction between the APIs of the TSA or ZAC, the signing software and the ZGW components (DRC, ZRC and NRC). The user interaction for selecting the documents and signers is out of scope, this is the responsibility of the TSA or ZAC. The same goes for the user interaction of the actual signing of the documents, that is the responsibility of the signing software.
39+
40+
## Existing implementations
41+
42+
The pattern described here is already implemented and used in production settings by the signing applications [ValidSign](https://www.validsign.eu/) and [Zynyo](https://zynyo.com/) and by the TSA [Rx.Mission](https://rxmission.nl/). These existing implementations use OneGround as the ZGW implementation, but as this pattern only uses standard behaviour of the ZGW components, it should work on any compliant ZGW implementation.
43+
44+
## Technical details
45+
46+
### Authentication
47+
48+
#### Authentication on the ZGW requests
49+
50+
The requests to the ZGW components use the standard authentication for the ZGW API: a JWT generated based on a ClientId and secret. See the [OneGround documentation](/docs/usage-of-clientids) or the general [ZGW documentation](https://vng-realisatie.github.io/gemma-zaken/themas/achtergronddocumentatie/authenticatie-autorisatie) for details.
51+
52+
#### Authentication on the trigger message
53+
54+
The type of authentication on the trigger message is determined by the signing software and might vary between vendors. Acceptable authentication methods include usage of an api-key or a bearer token based on a ClientId and Secret. Note that in the case of ClientId and Secret, this will be a separate ClientId from the one used to access the ZGW API. The TSA or ZAC sending the trigger message should implement the authentication method for the signing software vendor(s) it integrates with.
55+
56+
#### Authentication of the signer
57+
58+
Before the documents are presented to the signer, this person should authenticate themselves. Handling this authentication is the responsibility of the signing software, however the required type of authentication can be set in the trigger message send by the TSA or ZAC. See the details of the trigger message for more on this.
59+
60+
### Trigger message
61+
62+
To initiate the signing process, the TSA or ZAC should post a trigger message to the signing software in this format:
63+
64+
```
65+
{
66+
"naam": "...", // Name of signing transaction, can be displayed to the signer(s) by the signing software
67+
"eigenaar": "[email protected]", // e-mail of user that initiates the signing transaction
68+
"zaak": {
69+
"uuid": "2cc803a9-7404-4289-8f3d-f2300f666eac", // uuid of the case
70+
"url": "$url" // ZRC url of the case
71+
},
72+
"bewijs_informatieobjecttype": "$url", // informationobjecttype for evidence document
73+
"documenten": [ // list of documents to sign
74+
{
75+
"uuid": "f491249e-0651-4d22-a8a8-bb35885e9245", // uuid of the document
76+
"url": "$url", // DRC url of the document
77+
"titel": "Some document", // title of the document
78+
"versie": 1, // version of the document to be signed
79+
"bestandsnaam" : "some file.docx" // filename of the document;
80+
}
81+
],
82+
"ondertekenaars": [ // list of signers
83+
{
84+
"e-mail": "[email protected]", // e-mail of signer
85+
"voornaam": "John", // first name of signer
86+
"achternaam": "Doe", // last name of signer
87+
"identificatie": "Signer1", // string to identify the signer; can be used to relate this signer to specific signing areas or placeholders in the documents (not all signing software might need this property but supplying it should not cause errors)
88+
"volgorde": 1, // order number used to determine in which order the signers should sign in case of multiple signers
89+
"authenticatie": { // Method of authentication this signer should use to identify themselves
90+
"methode": "sms",
91+
"waarde": "+31655555555" // phone number of signer
92+
}
93+
}
94+
]
95+
}
96+
```
97+
98+
Some details about properties that might not be clear from the description:
99+
100+
- _bewijs_informatieobjecttype_: Depending on the vendor and/or configuration of the signing software, a separate evidence document with proof of signing might be added to the case as part of the signing flow. This property specifies which informatieobjecttype should be used for this document.
101+
- _documenten[ ].versie_: The exact version of the document to be signed. The signing software should retrieve this version to present it to the signers.
102+
- _documenten[ ].bestandsnaam_: Signing software often accepts different document formats (i.e. Microsoft Word, Open Office, PDF) as input, but the signed version will always be PDF. In case the format of the signed version differs from the original, the filename should be updated with the new extension.
103+
- _ondertekenaars[ ].identificatie_: A string that can be used by the signing software to determine where in the document the signature of this signer should appear (usage of this field might vary between vendors and not all signing software might require this field)
104+
- _ondertekenaars[ ].authenticatie_: This property indicates how the signer should authenticate themselves before the documents to be signed are presented to them. The following options should be supported at minimum:
105+
- _authenticatie = null_: when this property is set to null, the minimal form of authentication should be used. What this minimal is, is dependent on the signing software.
106+
- _authenticatie.methode = sms_: The signer should authenticate themselves using an sms with a one-time passcode (SMS OTP); for this method the property _authenticatie.waarde_ should also be provided, with the mobile phone number of the signer in international format.
107+
108+
### Response to the trigger message
109+
110+
If the trigger message is received correctly, the signing software should respond with status code 200 and this message:
111+
112+
```
113+
{
114+
"transaction_id": "2opbDxqSB8BX3137ulqdw2q9_Mw=" // unique id of this signing transaction; format to be determined by the signing software
115+
}
116+
```
117+
118+
### NRC notification when signing is complete or has failed
119+
120+
When the signing is complete and the signing software has uploaded the signed documents to the DRC, it should send a notification to the NRC. The TSA or ZAC can subscribe to these notifications, for instance to notify the user that initiated the signing request.
121+
122+
Note that signing documents is a very asynchronous sequence: it might be several hours, days, or even longer before all signers have signed all documents in the signing request. That means the time between sending the trigger message and receiving the NRC notification can be quite long. It is recommended that while the signing transaction is in progress, the TSA or ZAC indicates this to users in the UI where the documents are displayed so the user knows these documents are awaiting signing.
123+
124+
When signing is completed successfully, the request to the NRC should be:
125+
126+
```
127+
{
128+
"kanaal": "documentacties",
129+
"hoofdObject": ""$url"", // ZRC url of the case
130+
"resource": "zaak",
131+
"resourceUrl": ""$url"", // ZRC url of the case
132+
"actie": "OndertekenenVoltooid", // this value indicates this notification is about a successfully completed signing transaction
133+
"aanmaakdatum": "2025-01-01T12:00:00Z", // date-time of this notification
134+
"kenmerken": {
135+
"transaction_id": "2opbDxqSB8BX3137ulqdw2q9_Mw=" // id of this signing transaction, same as in the response on the trigger message
136+
}
137+
}
138+
```
139+
140+
When signing has failed, is cancelled or has otherwise not completed successfully, the request to the NRC should be:
141+
142+
```
143+
{
144+
"kanaal": "documentacties",
145+
"hoofdObject": ""$url"", // ZRC url of the case
146+
"resource": "zaak",
147+
"resourceUrl": ""$url"", // ZRC url of the case
148+
"actie": "OndertekenenAfgebroken", // this value indicates this notification is about a failed signing transaction
149+
"aanmaakdatum": "2025-01-01T12:00:00Z", // date-time of this notification
150+
"kenmerken": {
151+
"reden": "reason", // string specifying why the transaction has not completed, for instance "refused by signer", "retracted" or "technical error ..." (preferably in Dutch, so it can be presented to the end user in the TSA or ZAC)
152+
"transaction_id": "2opbDxqSB8BX3137ulqdw2q9_Mw=" // Id of this signing transaction, same as in the response on the trigger message
153+
}
154+
}
155+
```
156+
157+
Some details about these notifications:
158+
159+
- _kanaal = documentacties_: As there is no channel for this action defined in the ZGW specification and it is not allowed to post custom notifications to existing channels, this article proposes a custom channel for actions on documents. Adding new channels is allowed within the NRC specification. This also ensures only applications interested in these notifications will receive them.
160+
- _resource = zaak_: It might seem counter-intuitive that the resource of this notification is _zaak_ instead of _document_ and that the _resourceUrl_ and _hoofdObject_ properties are set to the url of the case. The reason for this is that one signing transaction can concern multiple documents but will always be initiated from the context of a single case.

‎blog/authors.yml

+8
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,11 @@ giedriusgrabauskas:
77
socials:
88
github: Grabauskas
99
linkedin: giedriusgrabauskas
10+
michielnijdam:
11+
name: Michiel Nijdam
12+
title: Information Analyst @ Visma Roxit
13+
image_url: https://github.com/MNIJ.png
14+
page: true
15+
socials:
16+
github: MNIJ
17+
linkedin: michielnijdam

‎blog/tags.yml

+4
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,7 @@ security:
22
label: Security
33
permalink: /security
44
description: Security related articles
5+
integrations:
6+
label: Integrations
7+
permalink: /integrations
8+
description: Articles about best practices and patterns for integrating client application with the ZGW API

‎static/img/signing-sequence.png

76.4 KB
Loading

0 commit comments

Comments
 (0)