Signing Lacuna Signer documents on Amazon ECS Fargate with CloudFormation

This page specifies a single-instance deployment of Bulk Signer on Amazon Web Services that signs documents created in Lacuna Signer. A user or the API creates a document in a Signer folder bound to a Bulk Signer signing profile; Bulk Signer signs it with the organization's certificate, whose private key is held in AWS KMS, and Signer stores the signed document. The deployment consists of:

• the Bulk Signer container image, running as one Amazon ECS task on AWS Fargate behind an Application Load Balancer;
• the operational store in Amazon RDS for SQL Server;
• the work share and the signing certificate in one Amazon S3 bucket;
• the signing key in AWS KMS;
• a signing profile that uses the SignerFolder method;
• the Signer:WebhookSecret webhook, through which Signer notifies Bulk Signer of new documents.

The infrastructure is the one specified in Amazon ECS Fargate. On this page a CloudFormation template creates all of it in one stack (step 5), on an empty AWS account. Three things stay outside the stack and are prepared before it: the signing key, imported from the PFX into KMS (step 2); the container image, copied into ECR (step 3); and the secrets whose values a person types (step 4). After the stack come the DNS record and the Lacuna Signer side: the profile, the webhook and a test (steps 6 to 10).

The same deployment, built command by command with the AWS CLI instead of a template, is specified in Amazon ECS Fargate + Lacuna Signer. Both pages produce the same resources and the same configuration; this one leaves fewer commands to run.

An environment already deployed by hand from Amazon ECS Fargate is not taken over by the template. To add the Lacuna Signer integration to it, follow step 1, create the two Lacuna Signer secrets of step 4, add the Signer settings of Bulk Signer configuration to a new task definition revision, deploy it, and follow steps 8 to 10.

The procedure was validated in a homologation environment: a PDF created in Lacuna Signer was signed by the Fargate task with an e-CNPJ certificate whose key was held in AWS KMS, in a job with a total processing time of 1.2 seconds. On 2026-11-11 the template was deployed in sa-east-1 with the commands of steps 5 and 7, on a Windows workstation with Git Bash: the stack was complete 18 minutes after create-stack, every check of step 7 passed on the first attempt, an update with aws cloudformation deploy took three minutes, and the stack was then deleted.

Minimum version: 2.20.0

The SignerFolder method and the Signer:WebhookSecret key were introduced in 2.16.0. The S3 storage provider, the AwsKms certificate source and the Auth:SessionKeyRing:Placement key were introduced in 2.20.0. Earlier images refuse the configuration on this page at boot.

Single-instance constraint

Cluster mode is supported on Azure App Service only, and an S3 work share is refused when Cluster:Enabled is set. The ECS service the stack creates is configured so that two tasks never run concurrently, including during a deployment. Deployments that require more than one instance must use Azure App Service (cluster mode).

Architecture

Connections

Compared with a deployment that signs files only, three connections are added. None of them is an AWS resource.

Direction	Content	Credential
Signer → load balancer → task	The webhook: POST https://<host>/api/signer/notifications	Signer:WebhookSecret, sent as Authorization: Bearer
Task → Signer	The sweep, the read-back of each document, and the start and completion of each signature	Signer:ApiKey, sent as X-Api-Key
Task → KMS	kms:Sign, one call per signed document	The task role

Differences from file signing

Aspect	Behaviour with the SignerFolder method
Document content	No file passes through Bulk Signer. Signer sends the hash to sign, the task signs it in KMS, and Signer builds the signature into the document and stores it. Nothing enters a watched folder and nothing is written to work/output/. The signed document is downloaded from Signer.
Identification of the holder	Signer matches the participant of the document to the CPF contained in the profile's certificate. The certificate must therefore be an ICP-Brasil e-CPF or e-CNPJ (which contains the CPF of its responsible person).
Signature format	Signer selects the format: PAdES for a PDF, XAdES for XML, CAdES for any other type. The profile's own format setting is ignored.

Function of Signer:WebhookSecret in performance

Discovery mechanisms

Bulk Signer has two mechanisms for detecting a document that awaits its signature:

Mechanism	Operation	Availability
Sweep	Every Signer:FolderSweepIntervalSeconds (default: 300 seconds), the task lists the pending documents of every bound folder and reads each one back from Signer.	Always active. Requires only Signer:ApiKey.
Notification	Signer calls POST /api/signer/notifications when a document is created, signed or approved. The task queues a check for the document named in the call, responds immediately, and reads that document back.	Only when Signer:WebhookSecret is set. Without it, the route returns 404.

Effect of the setting

Aspect	Sweep only	With Signer:WebhookSecret
Time until a document is detected	Up to the sweep interval: 0 to 5 minutes by default, 2.5 minutes on average.	Seconds.
Calls to the Signer API	On every pass, one listing per bound folder plus one read per pending document in it, regardless of whether anything changed.	One read per notified document.
Flows with several participants	Each hand-over to the holder waits for a sweep.	The notification of the step preceding the holder's is the event through which the holder's turn is detected, in seconds.

The detection time can also be reduced, without the webhook, by lowering Signer:FolderSweepIntervalSeconds. Its minimum is 60 seconds, and every pass repeats the same listing and the same reads. At the minimum, the number of calls to Signer is five times that of the default, and a document still waits up to one minute. With the webhook, the number of calls is proportional to the number of events, and the sweep interval can remain at the default or be increased.

Scope

Property	Specification
Signature duration	Not affected. The setting changes the time until a document is detected, not the time required to sign it. In the homologation environment, a job took 1.2 seconds, queue wait included. Throughput is determined by Pipeline:MaxConcurrency and by the KMS quota.
Delivery guarantee	Provided by the sweep, not by the notification. If Signer cannot reach the load balancer, or a delivery is lost, the document is signed at the next sweep. A document is delayed, never lost.
Trust in the notification	None. A notification identifies which document to read; no other content of it is used. The document is read back from Signer with Signer:ApiKey before a job is created.

Security properties

The route is public, and the secret is the only element that distinguishes a call from Signer from any other call.

Property	Specification
Minimum length	32 characters. Leading or trailing whitespace is refused at boot.
Comparison	In fixed time.
Call without the secret	401.
Effect of a forged call that presents the secret	At most, the task reads one document from Signer.

Prerequisites

Requirement	Specification
Tools	The AWS CLI v2, authenticated (aws sts get-caller-identity must succeed), and a bash shell for the commands on this page (on Windows, Git Bash from Git for Windows). Docker, to copy the image (step 3). PowerShell 7 and OpenSSL 3.x (included with Git for Windows), for the key import (step 2). jq, which ships with neither Windows nor Git for Windows (winget install jqlang.jq; brew install jq on macOS; apt install jq on Linux), to read the responses in steps 7 to 10 and to push the image from Docker Desktop for Windows.
The template	bulksigner-ecs-fargate.yaml, saved in the working directory. It is also in the product repository, under docs/samples/.
IAM permissions	Permission to create a CloudFormation stack with named IAM resources (CAPABILITY_NAMED_IAM) and the resources it creates: S3, EC2 security groups, RDS, Secrets Manager, IAM (iam:CreateRole, iam:PutRolePolicy, iam:PassRole), ACM, Elastic Load Balancing, CloudWatch Logs, ECS and Lambda; plus KMS for step 2 and ECR for step 3. The PowerUserAccess policy alone is insufficient: it is denied iam:CreateRole.
Registry credentials	The credentials Lacuna issued for the container image. See Obtaining the product.
Licence	The PKI SDK licence.
DNS	A hostname that Signer can reach over the internet, and write access to the DNS zone that is authoritative for it. Confirm the delegation with dig +short NS example.com: a domain can have a Route 53 hosted zone in the account while being delegated to another provider.
Lacuna Signer organization	An organization on a Lacuna Signer instance, and a user with the organization administrator role. That role is required to register the webhook.
Lacuna Signer API key	An API key of that organization (step 1.2).
Signing material	The PFX file of an ICP-Brasil e-CPF or e-CNPJ certificate, with an RSA 2048, 3072 or 4096 key, and its password. A certificate that contains no CPF is refused when the profile is created.
Holder identification	The CPF contained in the certificate and an e-mail address of the holder. Documents must name the holder as a participant with exactly that CPF.
Microsoft Entra ID (optional)	Only for operator sign-in with a Microsoft account (step 4.2): a tenant, the Microsoft.Graph.Applications PowerShell module, and an account with the Cloud Application Administrator role or higher.

Shell variables

All commands on this page run in one shell session, initialised with the following variables:

export MSYS_NO_PATHCONV=1             # Git Bash only; see the note below
REGION=sa-east-1
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
NAME=bulksigner                       # the stack name and the prefix of every resource
BUCKET=$NAME-$ACCOUNT                 # created by the stack; bucket names are global
HOST=bulksigner.example.com           # the public hostname
SIGNER=https://<Lacuna Signer address>
PROFILE=aws-signer                    # the profile that signs in the Signer folder

Variable	Content
REGION	The AWS Region of every resource.
ACCOUNT	The AWS account ID of the authenticated identity.
NAME	The stack name, and the prefix of every resource name. From 2 to 21 lowercase letters, digits and hyphens.
BUCKET	The name of the bucket the stack creates. It includes the account ID because S3 bucket names are globally unique.
HOST	The public hostname of the deployment. Signer calls it.
SIGNER	The address of the Lacuna Signer API (step 1.1), without a trailing slash.
PROFILE	The name of the signing profile bound to the Signer folder. It must not be default.
MSYS_NO_PATHCONV	Turns off Git Bash's path conversion. Without it, an argument that starts with / is rewritten as a Windows path before it reaches the AWS CLI: aws logs tail /ecs/$NAME reads a log group named C:/Program Files/Git/ecs/…. In other shells the line has no effect.

Network placement

The stack uses the default VPC of the Region and its default subnets, one per Availability Zone. The task receives a public IP address for its outbound calls (ECR, KMS, S3, Secrets Manager, Lacuna Signer), and its security group admits inbound traffic from the load balancer only. In private subnets, the task requires a NAT gateway: Lacuna Signer is not an AWS service and cannot be reached through a VPC endpoint. The template does not support private subnets.

1. Lacuna Signer preparation

The following four items are defined in Lacuna Signer before any AWS resource is created.

1.1 API address

SIGNER is the address on which the Signer instance's API responds, which is not necessarily the address of the product's home page. Without a key, the API returns 401:

curl -s -o /dev/null -w '%{http_code}\n' $SIGNER/api/documents      # 401

1.2 API key

Create an application in the organization and generate its key, as specified in step 1 of Getting started with the Signer API.

Property	Specification
Access to the Applications menu	Restricted to the instance's system administrator. Without that access, request a key of the organization from the administrator of the Signer instance.
Format	<application>|<secret>. The application part may contain spaces.
Display	The key is displayed once, when it is created.
Scope	The organization in which it was created. The folder selector in step 8 lists only that organization's folders, and the task reads documents with this key.
Required access	A role that grants access to the folders and documents of the organization.

1.3 Folder

In Folders, select the organization and create a folder with the New folder icon.

Rule	Specification
Binding	One-to-one. Two profiles cannot share a folder.
Scope	The folder itself. A document in one of its subfolders is not signed.

The screenshots on this page use a folder named AWSTest.

1.4 PDF signature policy

Whether a PDF signed with an ICP-Brasil certificate receives the ICP-Brasil policy (AD-RB) or a basic PAdES signature is determined by Signer's UseBrazilianPdfSigningPolicies setting, not by Bulk Signer. The setting belongs to the Signer instance:

Signer instance	Where the setting is defined
On-premises	In the instance's settings.
Lacuna's cloud	By Lacuna. Request confirmation of the value in effect.

Define the policy before the first document is signed.

2. The signing key and the certificate

A PFX file contains two items with different destinations:

Item	Destination	Property
Private key	AWS KMS	KMS never returns it.
Certificate	A .cer file, which the stack checks against the key and uploads to the S3 bucket	Public material.

When the profile is opened, Bulk Signer reads both and refuses the pair if the public keys differ.

2.1 Import with the script

Import-PfxToKms.ps1 performs the complete import and prompts for the PFX password. The bucket does not exist yet, so the certificate is written to a file:

pwsh ./Import-PfxToKms.ps1 -PfxPath ./signer.pfx -Region $REGION -Alias $NAME \
  -CerPath ./signer.cer -SignerPrincipalArn arn:aws:iam::$ACCOUNT:role/$NAME-task

Parameter	Value	Description
-PfxPath	./signer.pfx	The PFX file holding the key and the certificate.
-Region	$REGION	The AWS Region in which the key is created.
-Alias	$NAME	The KMS alias. Steps 5 and 8 reference it as alias/<name>. The script stops if the alias already exists.
-CerPath	./signer.cer	The certificate, which step 5 passes to the stack.
-SignerPrincipalArn	The task role ARN	The principal exempted from the key policy's kms:Sign deny. The stack creates the role, with exactly this name, in step 5; an ARN can be referenced before the role exists.

Key policy. The key is created with the default KMS key policy plus an explicit deny of kms:Sign to every other principal. An account administrator therefore cannot sign as the certificate holder without first changing the key policy, and CloudTrail records that change.

2.2 Manual import

The following procedure is equivalent to the script and exposes each call. Run it in an empty directory, on a machine trusted to hold the PFX.

Import with the AWS CLI and OpenSSL

1. Extract the certificate and the private key. Each command prompts for the PFX password. A PFX protected with legacy algorithms requires -legacy on both commands.

openssl pkcs12 -in signer.pfx -clcerts -nokeys | openssl x509 -outform DER -out signer.cer
openssl pkcs12 -in signer.pfx -nocerts -nodes | openssl pkcs8 -topk8 -nocrypt -outform DER -out private-key.der
openssl x509 -inform DER -in signer.cer -noout -text | grep 'Public-Key'       # 2048, 3072 or 4096

signer.cer is public material. private-key.der is the private key in plaintext and exists until item 7.

2. Create a KMS key without key material. --origin EXTERNAL creates a key that awaits an import. The key spec must match the size reported in item 1. The policy is the default KMS key policy plus the deny that reserves kms:Sign for the task role:

cat > key-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    { "Sid": "EnableIamUserPermissions", "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::$ACCOUNT:root" }, "Action": "kms:*", "Resource": "*" },
    { "Sid": "OnlyNamedPrincipalsMaySign", "Effect": "Deny",
      "Principal": "*", "Action": "kms:Sign", "Resource": "*",
      "Condition": { "StringNotEquals": { "aws:PrincipalArn": ["arn:aws:iam::$ACCOUNT:role/$NAME-task"] } } }
  ]
}
EOF
KEY_ID=$(aws kms create-key --region $REGION --origin EXTERNAL --key-spec RSA_2048 --key-usage SIGN_VERIFY \
  --description "Bulk Signer signing key" --policy file://key-policy.json --query KeyMetadata.KeyId --output text)
aws kms create-alias --region $REGION --alias-name alias/$NAME --target-key-id $KEY_ID

3. Obtain the import parameters. KMS returns a single-use RSA public key (the wrapping key) and an import token, both valid for 24 hours:

aws kms get-parameters-for-import --region $REGION --key-id $KEY_ID \
  --wrapping-algorithm RSA_AES_KEY_WRAP_SHA_256 --wrapping-key-spec RSA_4096 > import-params.json
jq -r .PublicKey   import-params.json | base64 -d > wrapping-public-key.der
jq -r .ImportToken import-params.json | base64 -d > import-token.bin

4. Wrap the private key. An RSA private key exceeds the size that can be encrypted directly under the wrapping key, so KMS requires a hybrid algorithm, RSA_AES_KEY_WRAP_SHA_256. The private key is wrapped under a random AES-256 key, the AES key is encrypted under the wrapping key, and the import file is the concatenation of the two, with the encrypted AES key first.

openssl rand -out aes-key.bin 32
openssl enc -id-aes256-wrap-pad -K "$(xxd -p -c 64 aes-key.bin)" -iv A65959A6 \
  -in private-key.der -out key-material-wrapped.bin
openssl pkeyutl -encrypt -in aes-key.bin -out aes-key-wrapped.bin -inkey wrapping-public-key.der -keyform DER -pubin \
  -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256
cat aes-key-wrapped.bin key-material-wrapped.bin > encrypted-key-material.bin

5. Import the key material.

aws kms import-key-material --region $REGION --key-id $KEY_ID \
  --encrypted-key-material fileb://encrypted-key-material.bin --import-token fileb://import-token.bin \
  --expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

6. Compare the key with the certificate. The two output lines must be identical. This is the comparison Bulk Signer performs when the profile is opened:

aws kms get-public-key --region $REGION --key-id $KEY_ID --query PublicKey --output text | base64 -d \
  | openssl rsa -pubin -inform DER -noout -modulus
openssl x509 -inform DER -in signer.cer -noout -modulus

7. Remove the private key. Keep signer.cer for step 5.

rm -f private-key.der aes-key.bin key-material-wrapped.bin aes-key-wrapped.bin encrypted-key-material.bin import-token.bin

rm removes the directory entries only. The script overwrites each file with zeros before deleting it.

2.3 Verification

aws kms describe-key --region $REGION --key-id alias/$NAME \
  --query 'KeyMetadata.{State:KeyState,Usage:KeyUsage,Spec:KeySpec,Origin:Origin}'

Item	Expected value
State	Enabled
Usage	SIGN_VERIFY
Spec	RSA_2048, RSA_3072 or RSA_4096, according to the key
Origin	EXTERNAL
signer.cer	Exists in the working directory. The stack compares it with the key again in step 5.

The key is only as secure as every copy of the PFX

KMS never returns the private key, but the key existed outside an HSM before the import. Retain exactly one copy of the PFX in offline backup, which is the only means of importing the key again, and delete all other copies. For an ICP-Brasil A3 certificate, whose key is required to remain in certified hardware, resolve the compliance question before proceeding.

Key generated in KMS. A key created inside KMS instead requires a CSR signed by KMS and a certificate issued for it. That procedure is documented in Certificates.

3. The image

Copy the tag Lacuna specified for installation into an ECR repository in the account. Along with the registry credentials, Lacuna provides three values:

Variable	Content
REGISTRY	The registry host only, for example <name>.azurecr.io. It is the argument of docker login, which does not accept a path.
REPOSITORY	The image's path inside the registry, for example lacuna/bulksigner.
VERSION	The version to install, for example 2.20.0. Use an explicit version, not latest.

REGISTRY=<Lacuna registry host>
REPOSITORY=<image path in the registry>
VERSION=<version>
IMAGE=$ACCOUNT.dkr.ecr.$REGION.amazonaws.com/bulksigner:$VERSION

aws ecr create-repository --repository-name bulksigner --region $REGION \
  --image-tag-mutability IMMUTABLE --image-scanning-configuration scanOnPush=true

docker login $REGISTRY --username <registry-username>     # prompts for the token
docker pull --platform linux/amd64 $REGISTRY/$REPOSITORY:$VERSION
docker tag $REGISTRY/$REPOSITORY:$VERSION $IMAGE

Push the image to ECR. On Linux and macOS:

aws ecr get-login-password --region $REGION \
  | docker login --username AWS --password-stdin $ACCOUNT.dkr.ecr.$REGION.amazonaws.com
docker push $IMAGE

On Docker Desktop for Windows, docker login to ECR fails with error storing credentials … The stub received bad data: the ECR token exceeds the size Windows Credential Manager accepts. An empty --config directory does not help, because Docker Desktop keeps using Credential Manager. Write the token straight into the config.json of a temporary directory and push with it:

mkdir -p .docker-ecr
aws ecr get-authorization-token --region $REGION --query 'authorizationData[0].authorizationToken' --output text \
  | jq -R --arg r "$ACCOUNT.dkr.ecr.$REGION.amazonaws.com" '{auths: {($r): {auth: .}}}' > .docker-ecr/config.json
docker --config .docker-ecr push $IMAGE
rm -rf .docker-ecr

The directory holds an ECR access token valid for 12 hours; the rm removes it. Confirm the push:

aws ecr describe-images --region $REGION --repository-name bulksigner --query 'imageDetails[].imageTags' --output text

4. Secrets entered by hand

4.1 Secrets

The deployment reads six secrets. The stack generates three of them; the values of the other three are issued outside AWS and are entered by hand before the stack is created. The template receives only their ARNs, never their values.

Secret	Content	Created by	Injected as
$NAME/sql-app	JSON with username, password and connectionString	The stack	ConnectionStrings__Default (key connectionString)
$NAME/auth-api-key	A random 48-character key: the REST API's X-API-Key and the dashboard's sign-in key	The stack	Auth__ApiKey
$NAME/signer-webhook-secret	The token Signer presents on a notification: 48 characters, without punctuation	The stack	Signer__WebhookSecret
$NAME/pki-sdk-license	The PKI SDK licence	By hand, below	Signing__PkiSdkLicense
$NAME/signer-api-key	The Lacuna Signer API key from step 1.2, in the format <application>|<secret>	By hand, below	Signer__ApiKey
$NAME/entra-client-secret	The client secret of the Microsoft Entra ID app registration (optional)	By hand, step 4.2	Auth__EntraId__ClientSecret

Create the two required secrets from a prompt that does not echo input, and keep their ARNs for step 5. Paste the Signer API key exactly as Signer displayed it, including any spaces in the application part:

read -rsp 'PKI SDK licence: ' VALUE; echo
PKI_ARN=$(aws secretsmanager create-secret --region $REGION --name $NAME/pki-sdk-license \
  --secret-string "$VALUE" --query ARN --output text)
read -rsp 'Lacuna Signer API key: ' VALUE; echo
SIGNER_KEY_ARN=$(aws secretsmanager create-secret --region $REGION --name $NAME/signer-api-key \
  --secret-string "$VALUE" --query ARN --output text)
unset VALUE

The secrets can also be created in the console (Other type of secret → Plaintext, containing the bare value only); then copy each ARN into PKI_ARN and SIGNER_KEY_ARN.

4.2 Microsoft Entra ID sign-in (optional)

By default the dashboard's sign-in page asks for the $NAME/auth-api-key key. With an Auth:EntraId section it offers Sign in with Microsoft instead, and two app roles control access: Administrator for the operator dashboard and Approver for the approver pages (Configuration). The REST API's X-API-Key does not change. To sign in to the dashboard with the API key, skip this step.

Configure it before the stack

Sessions created by the API-key sign-in stop working once the Auth:EntraId section is present. Configured at this point, Entra ID is part of the stack's first deployment, and the profile in step 8 is created with the Microsoft account. To add it to a running stack, see Operations.

1. Create the app registration. Give the environment its own registration, not one shared with another environment. New-BulkSignerEntraApp.ps1 creates a single-tenant registration with the redirect URI https://$HOST/signin-oidc, the Administrator and Approver app roles, the email claim, and an enterprise application with Assignment required:

pwsh ./New-BulkSignerEntraApp.ps1 -BaseUrl https://$HOST -DisplayName "Lacuna Bulk Signer (AWS)"

The script refuses a display name that already exists in the tenant. At the end it prints, once, the Auth__EntraId__TenantId, Auth__EntraId__ClientId and Auth__EntraId__ClientSecret block.

2. Store the values. The client secret goes into Secrets Manager from a prompt that does not echo; the tenant and the client are not secrets:

read -rsp 'Client secret: ' VALUE; echo
ENTRA_ARN=$(aws secretsmanager create-secret --region $REGION --name $NAME/entra-client-secret \
  --secret-string "$VALUE" --query ARN --output text)
unset VALUE
TENANT_ID=<the Auth__EntraId__TenantId value>
CLIENT_ID=<the Auth__EntraId__ClientId value>

Clear the console afterwards.

3. Assign people. In the Entra admin center, under Enterprise applications → the application → Users and groups, assign the Administrator app role to each operator. An account with no assignment cannot sign in, and an account that authenticates with neither role is refused.

Item	Description
Dependence on forwarded headers	Sign-in builds its redirect URI from the scheme Bulk Signer sees. The stack sets Hosting:ForwardedHeaders; without it the URI would be http://…/signin-oidc, and Microsoft refuses it with AADSTS50011.
Client secret expiry	The script's default lifetime is twelve months. An expired secret fails only at sign-in time, with an AADSTS error. Rotate it into the same secret and force a new deployment (Operations).

5. The stack

5.1 What the stack creates

One CloudFormation stack, named $NAME, creates the whole AWS infrastructure of the deployment. Every resource name starts with $NAME.

Resource	Name	Specification
S3 bucket	$NAME-<account>	All public access blocked; incomplete multipart uploads aborted after one day; the inputs/default/ folder; the certificate at signing-material/$NAME.cer.
Security groups	$NAME-alb, $NAME-task, $NAME-db	TCP 443 and 80 from 0.0.0.0/0 into the load balancer; TCP 8080 from the load balancer into the task; TCP 1433 from the task into the database.
RDS for SQL Server	$NAME	sqlserver-ex 16.00 (SQL Server 2022), db.t3.small, 20 GiB gp3, encrypted, not publicly accessible, seven-day backups. The master user bsadmin has a password managed by RDS in Secrets Manager.
Database and login	BulkSigner, bulksigner	Created by a one-off Fargate task that runs sqlcmd (image mcr.microsoft.com/mssql-tools) as the master user: the database with READ_COMMITTED_SNAPSHOT on, and a login that holds db_datareader, db_datawriter and db_ddladmin, not db_owner. The stack fails if the task exits with a code other than 0.
Secrets	$NAME/sql-app, $NAME/auth-api-key, $NAME/signer-webhook-secret	Generated by Secrets Manager (step 4.1). The connection string carries TrustServerCertificate=True, because the Bulk Signer image does not trust the Amazon RDS certificate authority (step 5 of Amazon ECS Fargate).
IAM roles	$NAME-exec, $NAME-task	$NAME-exec, assumed by Amazon ECS: AmazonECSTaskExecutionRolePolicy plus secretsmanager:GetSecretValue on the six secrets and on the RDS master secret (the latter for the database task only). $NAME-task, assumed by Bulk Signer: kms:DescribeKey, kms:GetPublicKey and kms:Sign on the key from step 2, s3:ListBucket on the bucket, and reading, writing and deleting its objects. Both trust ecs-tasks.amazonaws.com in the account only.
ACM certificate	—	For $HOST, with DNS validation (step 5.3). Not created when an existing certificate ARN is given.
Load balancer and target group	$NAME	Internet-facing, idle timeout 300 seconds, invalid header fields dropped. HTTPS listener with ELBSecurityPolicy-TLS13-1-2-2021-06; HTTP listener that redirects to HTTPS with 301. Target group on port 8080, health check /api/ready every 30 seconds, deregistration delay 30 seconds. The purpose of each setting is specified in step 7 of Amazon ECS Fargate.
Log groups	/ecs/$NAME, /aws/lambda/$NAME-provisioner	30-day retention.
Cluster, task definition and service	$NAME, $NAME, bulksigner	Fargate, 1 vCPU and 2 GB, X86_64, port 8080, stopTimeout 60. One task, with the deployment settings of step 5.5.
Lambda function	$NAME-provisioner	Runs the four operations CloudFormation has no resource type for: it finds the default VPC, writes the inputs/default/ folder, checks the certificate against the KMS key and uploads it, and creates the database. It is not in the VPC and calls AWS APIs only.

Port 443 must remain reachable by Signer

The webhook is a call from Signer to the load balancer. If the $NAME-alb group is restricted to specific source addresses, the addresses from which the Signer instance calls must also be admitted; obtain them from the operator of the instance. If Signer cannot be admitted, omit the webhook. The sweep alone signs every document, with the delay specified in Function of Signer:WebhookSecret in performance.

The bucket uses three prefixes, which must not nest:

Prefix	Content	Written by	Used by the Signer folder
signing-material/	The signing certificate (.cer)	The stack, from step 2's signer.cer	Yes. Read when the profile is opened.
work/	The work share	Bulk Signer, at boot	No. Bulk Signer nevertheless does not start without a work share.
inputs/default/	A watched folder, for files signed by the default profile	The stack	No.

Versioning and Object Lock must remain disabled. The behavioural differences of an S3 work share are documented in Configuration.

5.2 Parameters

Parameter	Value on this page	Description
Prefix	$NAME	The prefix of every resource name. The task role is <Prefix>-task, the role named in step 2. Default: bulksigner.
HostName	$HOST	The public hostname.
ImageUri	$IMAGE	The image in ECR, from step 3.
KmsKeyAlias	alias/$NAME	The alias from step 2. Default: alias/bulksigner.
SigningCertificate	The base64 of signer.cer	The certificate from step 2, on one line. The stack refuses it if its public key is not the KMS key's, before any other resource depends on it, and uploads it to the bucket.
PkiSdkLicenseSecretArn	$PKI_ARN	Step 4.1.
SignerEndpoint	$SIGNER	The Signer API address, without a trailing slash. Empty for a deployment that signs files only: no Signer__* settings and no webhook secret.
SignerApiKeySecretArn	$SIGNER_KEY_ARN	Step 4.1. Required with SignerEndpoint.
CertificateArn	Empty	An issued ACM certificate for $HOST in $REGION. Empty: the stack requests one with DNS validation (step 5.3).
Route53HostedZoneId	Empty	Only when the stack requests the certificate and the zone authoritative for $HOST is a Route 53 hosted zone in the account: the stack then creates the validation record itself.
EntraTenantId, EntraClientId, EntraClientSecretArn	$TENANT_ID, $CLIENT_ID, $ENTRA_ARN	Step 4.2, optional. All three or none.
AppEnvironment, TrustLacunaTestRoot	Production, false	For a homologation environment that signs with Lacuna's test certificates: Staging and true (Configuration). The stack refuses true with Production.
DatabaseEngine, DatabaseEngineVersion, DatabaseInstanceClass	sqlserver-ex, 16.00, db.t3.small	Express edition is sufficient for a homologation environment; production environments require sqlserver-web or sqlserver-se.

5.3 Creation

aws cloudformation create-stack --region $REGION --stack-name $NAME \
  --template-body file://bulksigner-ecs-fargate.yaml --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=Prefix,ParameterValue=$NAME ParameterKey=HostName,ParameterValue=$HOST \
    ParameterKey=ImageUri,ParameterValue=$IMAGE ParameterKey=KmsKeyAlias,ParameterValue=alias/$NAME \
    ParameterKey=SigningCertificate,ParameterValue=$(openssl base64 -A -in signer.cer) \
    ParameterKey=PkiSdkLicenseSecretArn,ParameterValue=$PKI_ARN \
    ParameterKey=SignerEndpoint,ParameterValue=$SIGNER ParameterKey=SignerApiKeySecretArn,ParameterValue=$SIGNER_KEY_ARN \
    ${TENANT_ID:+ParameterKey=EntraTenantId,ParameterValue=$TENANT_ID ParameterKey=EntraClientId,ParameterValue=$CLIENT_ID ParameterKey=EntraClientSecretArn,ParameterValue=$ENTRA_ARN}

The last line adds the Entra ID parameters only when TENANT_ID is set (step 4.2). The stack can also be created in the console, under CloudFormation → Create stack → With new resources → Upload a template file, with the same parameters.

Certificate validation. When CertificateArn is empty, the stack waits for the ACM certificate to be validated, and stops there until the validation record exists. About a minute after creation starts, the record appears in the stack's events:

aws cloudformation describe-stack-events --region $REGION --stack-name $NAME \
  --query "StackEvents[?LogicalResourceId=='Certificate' && contains(ResourceStatusReason || '','CNAME')].ResourceStatusReason" \
  --output text

Create the returned CNAME record (Name and Value) in the authoritative zone. The stack continues once ACM has validated it, usually within minutes. With Route53HostedZoneId, this step is not needed.

5.4 Completion

Wait for the stack, then read its outputs:

aws cloudformation wait stack-create-complete --region $REGION --stack-name $NAME
aws cloudformation describe-stacks --region $REGION --stack-name $NAME --query 'Stacks[0].Outputs' --output table

Creation takes about 20 minutes, most of it for the RDS instance; a certificate validation adds the time until the record exists. The first boot of the task applies the database migrations; the stack is complete once the service is stable.

Output	Content
Url	https://$HOST/
DnsRecord	The CNAME record to create in step 6.
LoadBalancerDnsName	The load balancer's DNS name.
BucketName, KmsKeyArn	The bucket and the KMS key, as used in step 8.
AuthApiKeySecretArn, SignerWebhookSecretArn	The generated secrets read in steps 7, 8 and 9.
WebhookUrl	The URL registered in Signer in step 9.
LogGroupName	/ecs/$NAME.

If the creation fails, CloudFormation rolls it back and deletes what it created, the bucket included. The cause is in the first failed event:

aws cloudformation describe-stack-events --region $REGION --stack-name $NAME \
  --query "StackEvents[?ends_with(ResourceStatus,'FAILED')].[LogicalResourceId,ResourceStatusReason]" --output text

See Error reference. After a rollback, delete the stack (aws cloudformation delete-stack --region $REGION --stack-name $NAME) before creating it again.

5.5 The service

Setting	Value	Requirement
minimumHealthyPercent, maximumPercent	0, 100	Every deployment stops the running task before starting the new one.
Desired count	1	Must not be increased. Auto scaling must not be attached.
deploymentCircuitBreaker	enable=true, rollback=false	A failed deployment stops instead of rolling back, which would start a second task.
Availability Zone rebalancing	Off	Rebalancing starts a task before stopping one.
Health check grace period	300 seconds	The first boot applies the migrations before /api/ready answers.

5.6 Bulk Signer configuration

The stack writes the container's environment and secrets. A __ in an environment variable name corresponds to : in the configuration key.

Lacuna Signer connection. One host connects to one Signer organization, and every profile that uses the SignerFolder method uses these settings (Configuration).

Environment variable	Value in this deployment	Required	Description
Signer__Endpoint	The SignerEndpoint parameter	Yes	The address of the Signer API.
Signer__ApiKey	Secret $NAME/signer-api-key	Yes	Sent as X-Api-Key on every call to Signer: the sweep, the read-back of each document, and the start and completion of each signature. It also determines the organization whose folders the profile form lists.
Signer__WebhookSecret	Secret $NAME/signer-webhook-secret	No	Enables POST /api/signer/notifications and is the Bearer token Signer must present on it. Without it, the route returns 404 and documents are detected by the sweep only (see Function of Signer:WebhookSecret in performance).
Signer__FolderSweepIntervalSeconds	300 (the default)	No	The interval between listings of every bound folder, from 60 to 86400 seconds.

The following rules apply to the Signer keys:

• Joint requirement. Setting any key under Signer:, including the webhook secret alone, makes Signer:Endpoint and Signer:ApiKey mandatory at boot. The template sets all of them or none.
• Keys not used by this method. Signer:PollIntervalSeconds, Signer:TimeoutHours and Signer:MaxConsecutiveApiFailures apply to the LacunaSigner method only.

Other settings. The remaining keys are those of the base deployment and are specified in the Configuration reference of Amazon ECS Fargate. The following points are specific to this deployment:

Setting	Relevance to the Lacuna Signer integration
Signing:Certificate:*	The seed (initial load) of the default signing profile, applied on the first boot against an empty database only. The default profile cannot use the SignerFolder method; the profile created in step 8 references the same key and the same .cer. Every credential is InstanceRole, so no profile stores a secret.
Hosting:ForwardedHeaders:*	With forwarded headers applied, the task observes Signer's address instead of the load balancer's. The rate limit of the notification route (RateLimiting:SignerNotification, 600 calls per minute) is counted per caller address; without forwarded headers, all callers share one budget (Configuration). The stack sets the VPC's CIDR block as the known network.
Storage:Inputs:0:*	The watched folder for files.

6. DNS

Point the hostname at the load balancer, with the CNAME record in the DnsRecord output or, if the zone is hosted in Route 53, an alias record. Signer calls this hostname and validates its certificate; the ACM certificate satisfies that requirement.

7. Verification

curl -s https://$HOST/api/ready
KEY=$(aws secretsmanager get-secret-value --region $REGION --secret-id $NAME/auth-api-key --query SecretString --output text)
curl -s -H "X-API-Key: $KEY" https://$HOST/api/ready/details | jq '.checks[] | {name, ok, detail}'

In addition to the checks specified in step 9 of Amazon ECS Fargate (database, input-folder:default, storage-bucket:…, work-share-owner, pki-license), /api/ready/details reports the cloudhub check, with ok: true and the detail not configured (CloudHub:ApiKey), which is the normal value on this deployment, and two checks for the Lacuna Signer integration:

Check	Expected result at this point
signer-notifications	accepted; none has arrived at this instance since it started
signer-folder-sweep	ok: true. After the first pass: the last pass at this instance finished without a failure at …

If signer-notifications reports not accepted (Signer:WebhookSecret is not set), the stack was created with an empty SignerEndpoint.

The notification route can be tested without a credential:

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://$HOST/api/signer/notifications

Response	Meaning
401 (signer-notification.unauthorized)	Expected. The route is enabled and requires the Bearer token.
404 (signer-notification.not-configured)	No webhook secret is set.

With Entra ID (step 4.2), follow the sign-in's first redirect without signing in:

curl -s -o /dev/null -w '%{redirect_url}\n' https://$HOST/api/auth/entra-login

The URL must point to login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize, with the application ID and redirect_uri=https%3A%2F%2F<host>%2Fsignin-oidc. The https scheme is the value to confirm.

8. The signing profile

The default profile receives uploads that name no profile and watched folders that are bound to no profile, and the SignerFolder method accepts no files. The Signer folder therefore requires a dedicated profile.

8.1 Creation

Open the dashboard at https://<host>/ and sign in: with Sign in with Microsoft, using an account that holds the Administrator app role, if step 4.2 was applied; otherwise with the key stored in $NAME/auth-api-key, copied to the clipboard without being displayed:

aws secretsmanager get-secret-value --region $REGION --secret-id $NAME/auth-api-key \
  --query SecretString --output text | tr -d '\r\n' | clip

Open Signing profiles → New profile (/profiles/_new).

Field	Value
Name	aws-signer (the value of $PROFILE). The name cannot be changed after creation.
Signing method	Lacuna Signer folder (this host signs documents created at Signer)
Lacuna Signer folder	The folder from step 1.3, located with the name search. The selector lists the folders of the organization to which the API key belongs and stores the folder's ID.
Signature format	Ignored by this method. Signer selects the format.
Certificate source	AwsKms
Where is the file?	In an Amazon S3 object
AWS region, KMS key, AWS credential mode	$REGION, alias/$NAME, InstanceRole
S3 bucket, S3 object key, S3 region, S3 credential mode	$BUCKET, signing-material/$NAME.cer, $REGION, InstanceRole
S3-compatible endpoint	Empty. The field is for S3-compatible storage such as MinIO.
Path-style bucket addressing	Off, for the same reason.

When the method is selected, the form hides the settings Signer determines (the input folder, verification, encryption and the CNAB240 check) and saves them as disabled.

Select Create profile. The certificate is opened during the save: the task reads the .cer from S3, requests the public key from KMS and compares the two. The save is refused, and no profile is created, in the following cases:

Condition	Cause
KMS key not accessible	An incorrect alias, or a task role without kms:GetPublicKey on the key.
Certificate without a CPF	The certificate is not an e-CPF or e-CNPJ.
Folder already bound	Another profile signs in the selected folder.

A saved profile takes effect immediately. No restart is required.

8.2 Verification

curl -s -H "X-API-Key: $KEY" https://$HOST/api/profiles/$PROFILE | jq

The response must report the SignerFolder method and degraded = false. On the Signing profiles page, the profile's state is ready.

8.3 Separate certificate for the profile

To use a certificate other than that of the default profile, import it with a different alias. The bucket exists now, so the script can upload the certificate itself, under a different object key:

pwsh ./Import-PfxToKms.ps1 -PfxPath ./other.pfx -Region $REGION -Alias $NAME-other   -S3Bucket $BUCKET -S3Key signing-material/$NAME-other.cer   -SignerPrincipalArn arn:aws:iam::$ACCOUNT:role/$NAME-task

Before creating the profile, give the task role the new key in a policy of its own; otherwise the save is refused at kms:GetPublicKey. The stack manages only the role's bulksigner-app policy, so a policy with another name survives stack updates:

KEY_ARN=$(aws kms describe-key --region $REGION --key-id alias/$NAME-other --query KeyMetadata.Arn --output text)
aws iam put-role-policy --role-name $NAME-task --policy-name kms-$NAME-other --policy-document   "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"kms:DescribeKey\",\"kms:GetPublicKey\",\"kms:Sign\"],\"Resource\":\"$KEY_ARN\"}]}"

9. The webhook in Lacuna Signer

9.1 Registration

Copy the secret to the clipboard, so that it is not displayed. The clipboard command is clip on Windows, pbcopy on macOS and xclip -selection clipboard on Linux:

aws secretsmanager get-secret-value --region $REGION --secret-id $NAME/signer-webhook-secret \
  --query SecretString --output text | tr -d '\r\n' | clip

In Lacuna Signer, signed in as an administrator of the organization:

1. Open Organizations and select the organization.
2. In the Integration section, below the Webhooks card, select the + button. A new Webhook N panel opens. An organization can have several webhooks; an existing webhook of another system is not affected.
3. Fill in the fields as specified below.
4. Select Save, which remains disabled until the token is entered.
5. Clear the clipboard.

Field	Value	Requirement
URL	https://<host>/api/signer/notifications	The public hostname from step 6, not the load balancer's AWS DNS name. The scheme must be https: the port-80 listener responds with a redirect, and HTTP clients commonly resend a redirected POST as a GET, which delivers no notification.
Authentication type	Bearer	X-Api-Key must not be used. That header is Bulk Signer's own REST credential, and a notification that presents it is refused.
Authentication Token	The value of $NAME/signer-webhook-secret	Without the word Bearer. Signer adds the prefix.

The content Signer sends, and its authentication and retry behaviour, are specified in Webhooks.

9.2 Correspondence between Lacuna Signer and Bulk Signer

The complete configuration on the Signer side (steps 1 and 9):

Item in Lacuna Signer	Location	Corresponding item in Bulk Signer
The application and its API key	The instance's Applications	Signer:ApiKey
The folder	Folders, in the organization	The profile's Lacuna Signer folder
The webhook URL	Organizations → Integration	The public hostname, followed by /api/signer/notifications
The webhook token, of type Bearer	Organizations → Integration	Signer:WebhookSecret
UseBrazilianPdfSigningPolicies	The instance's settings	None. The setting alone determines the policy of PDF signatures.

9.3 Delivery behaviour

Behaviour	Specification
Event selection	Not available. Signer delivers every event of the organization to every webhook of the organization.
Events processed by Bulk Signer	DocumentsCreated, DocumentSigned and DocumentApproved. Every other event is answered 204, so that Signer does not retry it.
Retries	Signer retries a delivery that does not receive a 2xx response, up to ten times over several hours (Retries).
Effect of an incorrect token	Each delivery is answered 401, and the unauthorized outcome of bulksigner_signer_notifications_total increases.

10. Signing test

10.1 Document creation

In Lacuna Signer:

1. Select New document, upload a PDF, and select the organization and the bound folder.
2. Add the certificate holder as a participant of type Signer, with the name, the CPF contained in the certificate and the e-mail address. The holder can be the only participant or follow other participants; the task acts only when the pending action is the holder's.
3. Select Send.

10.2 Expected result

Within seconds, the dashboard's Jobs page lists a job with the document's name, marked Lacuna Signer, under the aws-signer profile:

The job passes through the following states:

State	Meaning
Queued	The document was detected and the job was created.
Processing	The task read the document back, started the signature and signed the hash in KMS.
Verifying	The signature was handed to Signer, which validates it and builds it into the document.
Completed	Signer accepted the signature.

In Lacuna Signer, the holder's action is concluded and the document contains the signature. If the holder was the last participant, the document's status in the folder is Completed:

The CloudTrail event history shows the task role's Sign call on the key within a few minutes.

10.3 Verification from the command line

curl -s -H "X-API-Key: $KEY" "https://$HOST/api/jobs?profile=$PROFILE" | jq
curl -s -H "X-API-Key: $KEY" https://$HOST/api/ready/details | jq -r '.checks[] | select(.name=="signer-notifications") | .detail'
curl -s -H "X-API-Key: $KEY" https://$HOST/api/metrics \
  | grep -E 'bulksigner_signer_(notifications_total|folder_signatures_total|folder_jobs_enqueued_total)'

Evidence	Expected value
signer-notifications check	accepted; the last arrived at this instance at <time>
bulksigner_signer_folder_signatures_total{outcome="signed"}	Incremented once per signature accepted by Signer.
bulksigner_signer_notifications_total	Counts deliveries, by outcome.

A document that is signed only minutes after its creation was detected by the sweep, which indicates that the notification did not arrive. In that case, the signer-notifications check still reports that none has arrived, or the unauthorized outcome is increasing. See Symptoms.

Operations

The operations of the base deployment are specified in step 11 of Amazon ECS Fargate. In this deployment, every change to the infrastructure or to the container's configuration is a stack update, not a change made in the console or with the service's own commands: a resource changed outside the stack is overwritten by the next update. aws cloudformation deploy keeps the value of every parameter that is not named:

aws cloudformation deploy --region $REGION --stack-name $NAME --template-file bulksigner-ecs-fargate.yaml \
  --capabilities CAPABILITY_NAMED_IAM --parameter-overrides <Parameter>=<value> ...

Operation	Procedure	Notes
Upgrade	Copy the new version into ECR (step 3), pause the pipeline (POST /api/pipeline/pause), wait until no job is Processing or Verifying, run the update with ImageUri=<new image>, and resume (POST /api/pipeline/resume).	A task stopped during a signature requires the next boot to ask Signer how the job ended, and some of those jobs end Failed with signer-folder.interrupted (Lacuna Signer integration). The sweep runs while the pipeline is paused: new documents become jobs and wait in the queue.
Secret rotation	Store the new value in the secret, then start a new task: aws ecs update-service --region $REGION --cluster $NAME --service bulksigner --force-new-deployment, with the pipeline paused as for an upgrade.	A task reads its secrets when it starts. A new deployment does not change the stack.
Webhook secret rotation	Store a new random value in $NAME/signer-webhook-secret, start a new task as above, then enter the new value in the webhook in Signer.	The same value exists on both sides. Between the two changes, notifications are answered 401; Signer retries them and the sweep detects the remaining documents. No document is lost.
Signer API key rotation	Create the new key in Signer, store it in $NAME/signer-api-key, start a new task as above, and only then revoke the previous key.	With a revoked key, every sweep fails, and the signer-folder-sweep check fails after three consecutive failed passes. The check does not affect /api/ready, so the load balancer keeps the task.
Certificate renewal	Pause the pipeline. Import the new PFX with a new alias (step 2) and run the update with KmsKeyAlias=alias/<new alias> and SigningCertificate=$(openssl base64 -A -in <new>.cer). Then, on the page of each profile that uses the key, set the new alias under Edit certificate (the S3 object key does not change), start a new task as above, and resume.	The stack holds one key: the update replaces signing-material/$NAME.cer and moves the task role to the new key, so until the profiles name the new alias and a task has restarted, they are degraded. If the new certificate contains a different CPF, documents pending in Signer for the previous CPF have no action for the new holder. Each is recorded once as Failed with signer-folder.no-holder-action. Notify the users who create documents before the change.
Folder change	Save the new folder on the profile's Certificate panel.	Takes effect without a restart. Documents remaining in the previous folder are no longer signed by the profile.
Adding Entra ID to a running stack	Run step 4.2, then the update with EntraTenantId, EntraClientId and EntraClientSecretArn, with the pipeline paused as for an upgrade.	Sessions created by the API-key sign-in stop working. Existing profiles do not change.
Deactivation	Remove the webhook in Signer, then disable the profile on its page or change its method.	Updating the stack with an empty SignerEndpoint while a profile still uses the method does not prevent the boot. The profile becomes degraded, and its reason names the two missing keys.
Removal	aws cloudformation delete-stack --region $REGION --stack-name $NAME	Deletes every resource of the stack except two, which are kept on purpose: the bucket, with the work share, and a final snapshot of the database. Delete them separately when they are no longer needed; a new stack with the same Prefix cannot be created while the bucket exists. Not part of the stack, and not deleted: the KMS key, the ECR image, and the secrets of step 4.

Interface contracts

Notification endpoint

POST /api/signer/notifications is called by Lacuna Signer and authenticated with Authorization: Bearer <Signer:WebhookSecret>. The complete contract is specified in REST API.

Response	Code	Condition
202	—	A document in a bound folder was queued for a check, or was already queued.
204	—	Any other authenticated delivery: an event that cannot make a document await a signature, a folder that is not bound, the folder of a disabled profile, or a body that cannot be read.
401	signer-notification.unauthorized	The Bearer token is absent or incorrect, or another scheme was used.
404	signer-notification.not-configured	Signer:WebhookSecret is not set.
429	—	The rate limit of the route (RateLimiting:SignerNotification) was exceeded. Signer retries the delivery.
503	signer-notification.unavailable	The operational store is unusable on the instance, or too many checks are queued. Signer retries the delivery.

Queued checks are held in memory. A restart discards those not yet performed, and the next sweep detects the corresponding documents.

Other endpoints used on this page

Authenticated requests send X-API-Key: <Auth:ApiKey>.

Method	Route	Authentication	Used by
GET	/api/ready, /api/ready/details	Anonymous; API key for the details	Verification (steps 7 and 10).
GET	/api/profiles/{name}	API key	Profile verification (step 8).
GET	/api/jobs?profile={name}	API key	Signing test (step 10).
GET	/api/metrics	API key	Signing test (step 10).
POST	/api/pipeline/pause, /api/pipeline/resume	API key	Deployment (Operations).
GET	<Signer__Endpoint>/api/documents	None	Confirms the Signer API address: 401 without a key (step 1.1).

AWS calls made by the task for the profile

Service	Action	Resource	When called
Amazon S3	s3:GetObject	signing-material/<name>.cer	When the profile is opened: during the save in step 8, and at each boot.
AWS KMS	kms:DescribeKey, kms:GetPublicKey	The signing key	When the profile is opened.
AWS KMS	kms:Sign	The signing key	Once per signed document.

Error reference

Error codes

Code	Origin	Meaning	Resolution
signer-notification.unauthorized	Notification route, 401	The token registered in Signer differs from the secret, was entered with the word Bearer, or the authentication type is not Bearer.	Correct the webhook in Signer (step 9).
signer-notification.not-configured	Notification route, 404	The webhook secret did not reach the task.	Check the task definition revision the service runs, and that the execution role can read the secret.
signer-folder.no-holder-action	Job, Failed	The document is in the bound folder but has no signing action for the certificate's CPF: the holder is absent, was added as an approver only, or was added without the CPF.	Add the holder as a signer with the CPF. The next sweep detects the new action. Not retriable.
signer-folder.signature-refused	Job, Failed	Signer refused the signature. Its validation results are recorded in the job history; the usual cause is the certificate (revoked, expired, or not the participant's).	Correct the cause reported by Signer, then retry the job.
signer-folder.interrupted	Job, Failed	The task stopped during the signature.	Check the document in Signer, then retry the job. A retry ends Canceled if the holder's action is already concluded.
error storing credentials … The stub received bad data	Docker Desktop for Windows, on the ECR docker login	Windows Credential Manager refuses the size of the ECR token.	Push the image with the .docker-ecr directory from step 3. An empty --config directory does not help.
The public key of SigningCertificate is not the public key of alias/…	Stack, resource SigningMaterial	signer.cer is not the certificate of the imported key.	Pass the .cer that step 2 wrote for that alias.
Alias arn:aws:kms:…:alias/… is not found	Stack, resource SigningMaterial	KmsKeyAlias names no key in the Region.	Pass the alias of step 2, with the alias/ prefix.
The database setup task … stopped with exit code …	Stack, resource DatabaseSetup	A sqlcmd command failed.	The first failed command is in the log the message names: aws logs tail /ecs/$NAME --region $REGION --log-stream-name-prefix dbsetup.
… already exists	Stack, any named resource	A resource with the same name exists: an earlier stack with the same Prefix, or its retained bucket.	Use another Prefix, or delete the earlier resource.
The stack stays in CREATE_IN_PROGRESS at Certificate	Stack, ACM	The validation record does not exist, or the zone that holds it is not the authoritative one.	Create the record of step 5.3, in the zone the dig +short NS check names.
Cannot create a snapshot because the database instance … is not currently in the available state	Stack deletion, resource Database	The stack was deleted while the RDS instance was still being created, and the final snapshot needs an available instance.	Wait for aws rds wait db-instance-available --region $REGION --db-instance-identifier $NAME, then delete the stack again.
Circuit breaker in the Service event	Stack, ECS	The task did not become healthy.	The task's log: aws logs tail /ecs/$NAME --region $REGION --log-stream-name-prefix bulksigner.
AADSTS50011	Microsoft Entra ID, at sign-in	The redirect URI sent is http://…, or it does not match the app registration.	Confirm that HostName is the hostname users open, and the registration's https://<host>/signin-oidc URI (step 4.2).
ThrottlingException, KeyUnavailableException	AWS KMS, recorded on the job	The KMS request quota, which is shared by every caller in the account and Region, was exceeded, or the key was unavailable.	See Troubleshooting.

A job that ends Canceled carries no code: the document was cancelled, refused or expired in Signer, or was already signed by the holder, before the task signed it. This is not a fault. Every signer-folder.* code is specified in Troubleshooting.

Symptoms

Symptom	Cause	Resolution
The task stops at boot and its log names Signer:Endpoint or Signer:ApiKey.	A key under Signer: is set without those two. Setting Signer__WebhookSecret alone is sufficient to require both.	Not reachable with the stack, which sets all of them or none. Check the task definition's environment.
The task stops at boot and its log names Signer:WebhookSecret.	The secret has fewer than 32 characters, or has leading or trailing whitespace, usually a trailing line break in the secret's value.	Store a new value without whitespace in $NAME/signer-webhook-secret and start a new task (Operations).
signer-notifications reports accepted; none has arrived… after a document was created.	Signer does not reach the load balancer: the URL registered in Signer is incorrect or uses http://, or the $NAME-alb security group does not admit Signer's addresses.	Correct the URL (step 9) or the $NAME-alb security group (step 5.1).
Documents are signed, but minutes after their creation.	The notification does not arrive, and documents are detected by the sweep.	See Troubleshooting.
The folder selector reports that Signer cannot be reached, or lists the folders of another organization.	Signer__Endpoint is not the address of the Signer API, or Signer__ApiKey belongs to another organization.	Correct SignerEndpoint with a stack update, or the secret $NAME/signer-api-key and start a new task (Operations).
Create profile is refused with a message about the certificate's CPF.	The certificate contains no CPF.	Use an ICP-Brasil e-CPF or e-CNPJ. See Troubleshooting.
Create profile is refused with a message about KMS or S3.	The task role lacks kms:GetPublicKey on the key or s3:GetObject on the .cer, the task role's ARN is not exempted from the key policy's deny, or the .cer does not match the key.	Correct the role or the key policy (steps 2 and 8.3). See Troubleshooting.
The signer-folder-sweep check fails.	Three consecutive passes failed. The usual cause is a revoked or incorrect Signer:ApiKey.	See Troubleshooting.

Errors of the base deployment that do not involve Lacuna Signer are specified in the Error reference of Amazon ECS Fargate.

Limitations

Not provided	Alternative
A signed file in S3	Signer stores the document. Download it from Signer; nothing is written to work/output/.
Verification of the result by Bulk Signer	None. Verification is disabled for this method, because Signer validates the signature when it builds it into the document.
The opposite direction: a file sent to Signer for a person to sign	The LacunaSigner method, which uses the same Signer:Endpoint and Signer:ApiKey, requires no further AWS change and is selected per profile. See Lacuna Signer integration.
More than one instance, verification of the database server certificate, metrics in CloudWatch, backups made by Bulk Signer	The limitations of Amazon ECS Fargate apply unchanged.