Pular para o conteúdo principal

Assinando documentos do Lacuna Signer com Docker no Ubuntu 24.04

Esta página especifica uma implantação de instância única do Bulk Signer em uma máquina virtual Ubuntu 24.04 LTS que assina documentos criados no Lacuna Signer. Um usuário ou a API cria um documento em uma pasta do Signer vinculada a um perfil de assinatura do Bulk Signer; o Bulk Signer o assina com o certificado da organização, cuja chave privada fica armazenada em um arquivo PFX na máquina virtual, e o Signer armazena o documento assinado. A implantação é composta por:

  • a imagem de container do Bulk Signer, executada como um container Docker gerenciado pelo Docker Compose;
  • o banco operacional em um banco SQLite local, no disco da máquina virtual;
  • o certificado de assinatura em um arquivo PFX, montado somente leitura no container;
  • um perfil de assinatura que usa o método SignerFolder, declarado na configuração e importado no primeiro boot.

Três partes são opcionais e independentes da assinatura em si: o HTTPS pelo nginx, que as outras duas exigem; o webhook do Signer:WebhookSecret, pelo qual o Signer notifica o Bulk Signer de novos documentos; e o login pelo Microsoft Entra ID para os operadores.

A instalação geral com Docker, para a assinatura de arquivos, está especificada em Instalação. A mesma integração com o Lacuna Signer na Amazon Web Services está especificada em Amazon ECS Fargate + Lacuna Signer.

Versão mínima: 2.16.0

O método SignerFolder e a chave Signer:WebhookSecret foram introduzidos na 2.16.0. Imagens anteriores recusam no boot a configuração desta página.

Restrição de instância única

Uma instância do Bulk Signer por pasta do Lacuna Signer. Um segundo container, ou uma segunda máquina virtual, vinculado à mesma pasta não é suportado. Uma implantação que exige mais de uma instância deve usar o Azure App Service (modo cluster).

Arquitetura​

Assinatura em uma pasta do Lacuna Signer com Docker no Ubuntu: usuário ou API cria um documento no Signer; o container o encontra pela varredura ou pelo webhook opcional, assina com a chave do PFX e devolve a assinatura ao Signer

Conexões​

DireçãoConteúdoCredencial
Container → SignerA varredura, a releitura de cada documento, e o início e a conclusão de cada assinaturaSigner:ApiKey, enviada como X-Api-Key
Signer → nginx → containerO webhook, quando configurado: POST https://<host>/api/signer/notificationsSigner:WebhookSecret, enviado como Authorization: Bearer
Operador → nginx → containerO dashboard e a API RESTAuth:ApiKey, ou uma sessão do Microsoft Entra ID
Máquina virtual → registry da LacunaO download da imagemAs credenciais do registry emitidas pela Lacuna

Toda conexão com o Signer parte da máquina virtual, exceto o webhook. Sem o webhook, a máquina virtual não precisa de acesso de entrada a partir da internet.

Diferenças em relação à assinatura de arquivos​

AspectoComportamento com o método SignerFolder
Conteúdo do documentoNenhum arquivo passa pelo Bulk Signer. O Signer envia o hash a assinar, o container o assina com a chave privada do PFX, e o Signer incorpora a assinatura ao documento e o armazena. Nada entra em uma pasta monitorada e nada é gravado em output/. O documento assinado é baixado do Signer.
Identificação do titularO Signer associa o participante do documento ao CPF contido no certificado do perfil. O certificado precisa, portanto, ser um e-CPF ou um e-CNPJ da ICP-Brasil (que contém o CPF do responsável).
Formato da assinaturaO Signer escolhe o formato: PAdES para um PDF, XAdES para XML, CAdES para qualquer outro tipo. A configuração de formato do próprio perfil é ignorada.
DescobertaUma varredura a cada Signer:FolderSweepIntervalSeconds (60 segundos nesta página). Com o webhook, em segundos. A varredura continua sendo a garantia de entrega: um documento é atrasado, nunca perdido.

Pré-requisitos​

RequisitoEspecificação
Máquina virtualUbuntu 24.04 LTS, x86 de 64 bits (amd64), com sudo. HTTPS de saída para download.docker.com, para o registry da Lacuna e para a instância do Lacuna Signer.
Credenciais do registryAs credenciais que a Lacuna emitiu para a imagem de container, e o host do registry, o caminho da imagem e a versão. Veja Obtendo o produto.
LicençaA licença do PKI SDK. Veja Obtendo a licença do PKI SDK.
Organização no Lacuna SignerUma organização em uma instância do Lacuna Signer. O cadastro do webhook exige um usuário com o papel de administrador da organização.
Chave de API do Lacuna SignerUma chave de API dessa organização (passo 1.2).
Material de assinaturaO arquivo PFX de um certificado e-CPF ou e-CNPJ da ICP-Brasil, e a senha dele. Um certificado que não contém CPF deixa o perfil degradado.
Identificação do titularO CPF contido no certificado. Os documentos devem indicar o titular como participante com exatamente esse CPF.
HTTPS (opcional)Um hostname que resolva para a máquina virtual, TCP 80 e 443 de entrada, e acesso de escrita à zona DNS dele. Exigido pelo webhook e pelo Entra ID.
Microsoft Entra ID (opcional)Um tenant, e uma conta com o papel Cloud Application Administrator ou superior.

Variáveis de shell​

Todos os comandos desta página são executados em uma única sessão de shell na máquina virtual, inicializada com as variáveis a seguir:

REGISTRY=<host do registry da Lacuna>
REPOSITORY=<caminho da imagem no registry>
VERSION=<versão>
SIGNER=https://<endereço do Lacuna Signer>
HOST=bulksigner.example.com # o hostname público; somente a partir da seção HTTPS
DIR=/opt/bulksigner
VariávelConteúdo
REGISTRYSomente o host do registry, por exemplo <nome>.azurecr.io. É o argumento do docker login, que não aceita um caminho.
REPOSITORYO caminho da imagem dentro do registry, por exemplo lacuna/bulksigner.
VERSIONA versão a instalar, por exemplo 2.20.1. Use uma versão explícita, não latest.
SIGNERO endereço da API do Lacuna Signer (passo 1.1), sem barra no final.
HOSTO hostname público da implantação. Usado somente a partir da seção HTTPS.
DIRO diretório da instalação. Todos os arquivos da implantação ficam nele.

1. Preparação do Lacuna Signer​

1.1 Endereço da API​

SIGNER é o endereço em que a API da instância do Signer responde, que não é necessariamente o endereço da página inicial do produto. Sem uma chave, a API retorna 401:

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

1.2 Chave de API​

Crie uma aplicação na organização e gere a chave dela, conforme especificado no passo 1 de Primeiros passos com a API do Signer.

PropriedadeEspecificação
Acesso ao menu AplicaçõesRestrito ao administrador de sistema da instância. Sem esse acesso, solicite uma chave da organização ao administrador da instância do Signer.
Formato<aplicação>|<segredo>. A parte da aplicação pode conter espaços.
ExibiçãoA chave é exibida uma única vez, na criação.
EscopoA organização em que foi criada. O container lê os documentos com essa chave.
Acesso exigidoUm papel que dê acesso às pastas e aos documentos da organização.

Leia a chave no shell a partir de um prompt que não a exibe. O passo 4 a grava na configuração:

read -rsp 'Chave de API do Lacuna Signer: ' SIGNER_API_KEY; echo

1.3 Pasta​

Em Pastas, selecione a organização e crie uma pasta com o ícone Criar pasta.

RegraEspecificação
VínculoDe um para um. Dois perfis não podem compartilhar uma pasta.
AlcanceA própria pasta. Um documento em uma subpasta dela não é assinado.

O perfil desta página é declarado na configuração, que identifica a pasta pelo ID. Liste as pastas da organização com a chave de API:

curl -s -H "X-Api-Key: $SIGNER_API_KEY" $SIGNER/api/folders | jq -r '.items[] | "\(.id) \(.name)"'

Cada linha mostra o ID de uma pasta e o nome dela. A resposta é a primeira página da listagem; em uma organização com muitas pastas, localize a pasta pelo nome. Guarde o ID e o nome:

FOLDER_ID=<o ID da pasta>
FOLDER_NAME=<o nome da pasta>

O jq é instalado no passo 2. Execute este comando depois dele, ou leia o ID na mesma resposta sem o jq.

1.4 Política de assinatura em PDF​

Se um PDF assinado com um certificado ICP-Brasil recebe a política da ICP-Brasil (AD-RB) ou uma assinatura PAdES básica é determinado pela configuração UseBrazilianPdfSigningPolicies do Signer, e não pelo Bulk Signer. A configuração pertence à instância do Signer:

Instância do SignerOnde a configuração é definida
On-premisesNas configurações da instância.
Nuvem da LacunaPela Lacuna. Solicite a confirmação do valor em vigor.

Defina a política antes de o primeiro documento ser assinado.

2. Docker Engine​

Instale o Docker Engine e o plugin do Compose a partir do repositório apt do Docker, conforme especificado em Install Docker Engine on Ubuntu, junto com o jq:

sudo apt update
sudo apt install -y ca-certificates curl jq
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker compose version

Todo comando docker desta página é executado com sudo.

O Docker ignora o ufw

Uma porta publicada pelo Docker fica acessível mesmo quando o ufw a nega: o Docker grava as próprias regras de filtragem de pacotes. Restrinja o acesso à porta 8080 com o firewall da rede ou da nuvem, ou publique-a somente em 127.0.0.1, como faz a seção HTTPS.

3. A imagem​

sudo docker login $REGISTRY --username <usuário do registry> # pede o token
sudo docker pull $REGISTRY/$REPOSITORY:$VERSION

A credencial fica armazenada em /root/.docker/config.json. O repositório é privado: um pull sem docker login responde authentication required.

4. Configuração​

Todos os arquivos da implantação ficam em $DIR:

ArquivoConteúdo
docker-compose.ymlO container, as montagens e a rede dele.
.envOs segredos, como variáveis de ambiente. Legível somente pelo root.
config/appsettings.Production.jsonO perfil de assinatura e a conexão com o Signer. Não contém segredo.
config/signing.pfxO certificado e a chave privada dele.
data/O banco SQLite e o key ring de sessão.
logs/Os arquivos de log, um por dia.
sudo mkdir -p $DIR/config $DIR/data $DIR/logs
cd $DIR

4.1 O arquivo do Compose​

sudo tee docker-compose.yml > /dev/null <<EOF
services:
bulksigner:
image: $REGISTRY/$REPOSITORY:$VERSION
container_name: bulksigner
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./data:/var/lib/bulksigner
- ./logs:/var/log/bulksigner
- ./config/appsettings.Production.json:/app/appsettings.Production.json:ro
- ./config/signing.pfx:/etc/bulksigner/signing.pfx:ro
env_file:
- .env
networks:
- bulksigner

networks:
bulksigner:
ipam:
config:
- subnet: 172.30.0.0/24
EOF
ElementoEspecificação
imageA versão de VERSION. Uma atualização altera esta linha (Operação).
portsHTTP simples na porta 8080. A seção HTTPS a restringe a 127.0.0.1.
./dataO banco SQLite (db/) e o key ring de sessão (keys/). Sem essa montagem, cada substituição do container perde o histórico de jobs e desconecta todos os operadores.
./config/signing.pfxLido a cada boot. Deve permanecer neste caminho enquanto o perfil o usar.
networksUma sub-rede fixa, para que a seção HTTPS confie em headers encaminhados somente desta rede. Se 172.30.0.0/24 estiver em uso na máquina virtual, escolha outra faixa privada e use-a nos dois lugares.

O health check da própria imagem consulta /api/health a cada 30 segundos.

4.2 Os segredos​

Leia os valores que uma pessoa digita a partir de prompts que não os exibem, e gere os demais:

read -rsp 'Licença do PKI SDK: ' LICENSE; echo
read -rsp 'Senha do PFX: ' PFX_PASSWORD; echo

sudo install -m 600 /dev/null .env
sudo tee .env > /dev/null <<EOF
Signing__PkiSdkLicense='$LICENSE'
Signing__ProfileSecretsKey='$(openssl rand -base64 36)'
Signing__Profiles__0__Certificate__Pfx__Password='$PFX_PASSWORD'
Signer__ApiKey='$SIGNER_API_KEY'
Auth__ApiKey='$(openssl rand -hex 24)'
EOF
unset LICENSE PFX_PASSWORD
VariávelDescrição
Signing__PkiSdkLicenseA licença do PKI SDK.
Signing__ProfileSecretsKeyCriptografa a senha do PFX no banco. O perfil fica armazenado no banco (Configuração), e a importação do primeiro boot se recusa a armazenar uma senha sem essa chave.
Signing__Profiles__0__Certificate__Pfx__PasswordA senha do PFX, importada para o perfil no primeiro boot.
Signer__ApiKeyEnviada como X-Api-Key em toda chamada ao Signer.
Auth__ApiKeyA chave de login do dashboard e o X-API-Key da API REST. No mínimo 16 caracteres.

Os valores ficam entre aspas simples para que o Docker Compose não interprete um $, um espaço ou um | neles. Um valor que contenha uma aspa simples deve ser editado no arquivo à mão.

Armazene a Signing__ProfileSecretsKey fora da máquina virtual

Copie-a agora para o gerenciador de senhas: sudo grep ^Signing__ProfileSecretsKey= .env. Sem ela, a senha do PFX armazenada não pode ser descriptografada, o perfil fica degradado, e o certificado dele precisa ser configurado de novo. Não há recuperação.

4.3 As configurações​

sudo tee config/appsettings.Production.json > /dev/null <<EOF
{
"Signing": {
"Profiles": [
{
"Name": "signer-folder",
"Format": "Pades",
"Method": "SignerFolder",
"Verify": false,
"ValidateCertificate": false,
"SignerFolder": { "Id": "$FOLDER_ID", "Name": "$FOLDER_NAME" },
"Certificate": {
"Source": "Pfx",
"Pfx": { "Path": "/etc/bulksigner/signing.pfx" }
}
}
]
},
"Signer": {
"Endpoint": "$SIGNER",
"FolderSweepIntervalSeconds": 60
}
}
EOF
ConfiguraçãoEspecificação
Signing:Profiles[0]O seed (carga inicial) do perfil de assinatura, importado somente no primeiro boot com o banco vazio. A partir daí o perfil fica armazenado no banco e é editado na página dele no dashboard; uma alteração posterior nesta seção é informada como ignorada no boot. Nenhum perfil default é criado.
Namesigner-folder. Não pode ser default e não pode ser alterado depois da importação.
FormatExigido pela configuração, ignorado pelo método: o Signer escolhe o formato.
Verify, ValidateCertificateDevem ser false; o padrão das duas é true. O Signer valida o certificado e a assinatura.
SignerFolder:IdA pasta do passo 1.3. Name é exibido somente na página do perfil.
Signer:EndpointO endereço da API do Signer. Junto com Signer:ApiKey, obrigatório assim que qualquer chave em Signer: é definida.
Signer:FolderSweepIntervalSecondsO intervalo entre as listagens da pasta, de 60 a 86400 segundos; o padrão é 300. 60 serve a uma implantação sem o webhook. Com o webhook, o padrão basta.

A especificação completa dessas chaves está em Configuração.

4.4 O certificado e as permissões​

O PFX precisa estar na máquina virtual. Copie-o da estação em que ele está, por exemplo com scp <arquivo>.pfx <usuário>@<máquina virtual>:.

O container é executado como o usuário de ID 1654, e não como root:

sudo cp <caminho do PFX> config/signing.pfx
sudo chown -R 1654:1654 data logs config/signing.pfx
sudo chmod 0400 config/signing.pfx

Confira a senha do passo 4.2 contra o arquivo antes do primeiro boot:

sudo openssl pkcs12 -in config/signing.pfx -noout -legacy # pede a senha do PFX

Uma senha que abre o arquivo não produz saída. Mac verify error: invalid password? significa uma senha errada ou outro arquivo. A senha do .env é importada para o banco somente no primeiro boot; depois dele, corrigir o .env não tem efeito (Referência de erros).

5. Início e verificação​

sudo docker compose up -d
sudo docker compose logs -f bulksigner # Ctrl+C para de acompanhar; o container continua rodando

O primeiro boot cria o banco, importa o perfil (Imported 1 signing profile into the operational store from Signing:Profiles.) e termina com o resumo Service ready. Os avisos ([WRN]) a seguir são esperados e não indicam um problema:

AvisoQuandoMotivo
Watched folder 'default' is unassignedA cada bootNenhum perfil recebe arquivos de uma pasta monitorada.
The migration operation 'PRAGMA foreign_keys = 0;' … cannot be executed in a transactionNo primeiro bootO Entity Framework informa uma migração que não pode ser executada em uma transação.
No XML encryptor configuredNo primeiro boot, e quando uma nova chave de sessão é criadaO key ring de sessão é gravado em data/keys sem uma criptografia própria, que o Linux não oferece.
Overriding HTTP_PORTS '8080' and HTTPS_PORTS ''A cada bootA imagem define ASPNETCORE_URLS, que prevalece sobre a porta padrão da imagem base. Os dois valores são a porta 8080.
The query uses the 'First'/'FirstOrDefault' operator without 'OrderBy'A cada boot, na 2.20.1Um aviso do Entity Framework sobre uma consulta interna.

Nos boots seguintes, a importação do perfil é substituída por Signing:Profiles names 1 profile(s) and is being ignored (passo 4.3).

KEY=$(sudo grep ^Auth__ApiKey= .env | cut -d= -f2- | tr -d "'")
curl -s http://localhost:8080/api/health
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/profiles/signer-folder | jq '{name, method, degraded}'
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/ready/details | jq '.checks[] | {name, ok, detail}'
VerificaçãoResultado esperado
/api/health"status":"healthy"
O perfil"method": "SignerFolder", "degraded": false
signer-folder-sweepok: true. A primeira passagem é feita no boot: the last pass at this instance finished without a failure at …
signer-notificationsnot accepted (Signer:WebhookSecret is not set) até o webhook ser configurado.
pki-licenseloaded

O motivo de um perfil degradado aparece na página dele no dashboard (Este perfil não consegue assinar) e na verificação signing-profile:signer-folder de /api/ready/details. Os motivos usuais são um certificado sem CPF e uma pasta que não existe no Signer.

6. Teste de assinatura​

No Lacuna Signer:

  1. Selecione Novo documento, faça upload de um PDF e selecione a organização e a pasta vinculada.
  2. Inclua o titular do certificado como participante do tipo Signatário, com o nome, o CPF contido no certificado e o e-mail. O titular pode ser o único participante ou vir depois de outros; o container só age quando a ação pendente é a do titular.
  3. Selecione Enviar.

Dentro do intervalo da varredura, ou em segundos com o webhook, a página Jobs do dashboard (http://<máquina virtual>:8080/jobs) lista um job com o nome do documento, no perfil signer-folder. O job passa pelos seguintes status:

StatusSignificado
Na filaO documento foi detectado e o job foi criado.
ProcessandoO container releu o documento, iniciou a assinatura e assinou o hash com a chave do PFX.
VerificandoA assinatura foi entregue ao Signer, que a valida e a incorpora ao documento.
ConcluídoO Signer aceitou a assinatura.

No Lacuna Signer, a ação do titular está concluída e o documento contém a assinatura. Pela linha de comando:

curl -s -H "X-API-Key: $KEY" "http://localhost:8080/api/jobs?profile=signer-folder" | jq
curl -s -H "X-API-Key: $KEY" http://localhost:8080/api/metrics | grep bulksigner_signer_folder_signatures_total

bulksigner_signer_folder_signatures_total{outcome="signed"} aumenta uma vez por assinatura aceita pelo Signer. A implantação está completa neste ponto; as três seções a seguir são opcionais.

HTTPS pelo nginx (opcional)​

O Bulk Signer escuta em HTTP simples. O nginx, na mesma máquina virtual, termina o TLS com um certificado do Let's Encrypt e encaminha para o container, que passa a ser acessível somente a partir da máquina virtual.

1. DNS e firewall. Crie um registro A para $HOST com o endereço público da máquina virtual, e libere TCP 80 e 443 de entrada no firewall da rede ou da nuvem. O Let's Encrypt valida o nome pela porta 80.

2. Publique o container na interface de loopback e confie no proxy. O nginx se conecta pela porta publicada, e o container vê a conexão chegar do gateway da rede do passo 4.1. Hosting:ForwardedHeaders faz o Bulk Signer ler o esquema e o endereço originais do cliente nos headers do nginx, somente a partir dessa rede:

sudo sed -i 's/"8080:8080"/"127.0.0.1:8080:8080"/' docker-compose.yml
sudo tee -a .env > /dev/null <<'EOF'
Hosting__ForwardedHeaders__Enabled=true
Hosting__ForwardedHeaders__KnownNetworks__0=172.30.0.0/24
EOF
sudo docker compose up -d
ConfiguraçãoEfeito
127.0.0.1:8080:8080A porta 8080 deixa de ser acessível de fora da máquina virtual, independentemente do ufw.
Hosting__ForwardedHeaders__EnabledLê X-Forwarded-Proto e X-Forwarded-For. Sem ela, o Bulk Signer vê http, e o login pelo Entra ID monta uma URI de redirecionamento http:// que a Microsoft recusa.
Hosting__ForwardedHeaders__KnownNetworks__0Confia em headers encaminhados somente a partir da rede do passo 4.1. Deve ser igual à subnet do arquivo do Compose.

Não defina também a ASPNETCORE_FORWARDEDHEADERS_ENABLED: definir as duas é recusado no boot.

3. Instale o nginx e o Certbot:

sudo apt install -y nginx certbot python3-certbot-nginx

4. O site. O dashboard mantém uma conexão WebSocket aberta, que exige os headers Upgrade e Connection:

sudo tee /etc/nginx/sites-available/bulksigner > /dev/null <<EOF
map \$http_upgrade \$connection_upgrade {
default upgrade;
'' close;
}

server {
listen 80;
server_name $HOST;
client_max_body_size 10m;

location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host \$host;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection \$connection_upgrade;
proxy_read_timeout 300s;
}
}
EOF
sudo ln -s /etc/nginx/sites-available/bulksigner /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

5. O certificado. O Certbot o obtém, acrescenta ao site o listener HTTPS e o redirecionamento de HTTP, e instala a renovação dele:

sudo certbot --nginx -d $HOST

6. Verificação:

curl -s https://$HOST/api/health

A resposta é "status":"healthy". De outra máquina, http://<máquina virtual>:8080 não conecta mais. O dashboard fica em https://$HOST/.

O webhook no Lacuna Signer (opcional)​

Sem o webhook, um documento espera a próxima varredura, até Signer:FolderSweepIntervalSeconds. Com ele, o Signer chama POST https://$HOST/api/signer/notifications quando um documento é criado, assinado ou aprovado, e o documento é assinado em segundos. A notificação identifica qual documento ler; nenhum outro conteúdo dela é considerado confiável, e o documento é relido do Signer com a Signer:ApiKey antes de um job ser criado. Exige a seção HTTPS.

1. O segredo. No mínimo 32 caracteres, sem espaços no início ou no fim:

echo "Signer__WebhookSecret='$(openssl rand -hex 32)'" | sudo tee -a .env > /dev/null
sudo docker compose up -d
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://$HOST/api/signer/notifications # 401

401 significa que a rota está habilitada e exige o token. 404 significa que o container não recebeu o segredo.

2. Cadastro. Exiba o segredo para copiá-lo, e depois limpe a tela:

sudo grep ^Signer__WebhookSecret= .env | cut -d= -f2- | tr -d "'"

No Lacuna Signer, com um administrador da organização:

  1. Abra Organizações e selecione a organização.
  2. Na seção Integração, abaixo do card Webhooks, selecione o botão +. Um novo painel Webhook N é aberto. Um webhook existente de outro sistema não é afetado.
  3. Preencha os campos conforme especificado abaixo e selecione Salvar.
CampoValorRequisito
URLhttps://<host>/api/signer/notificationsO esquema deve ser https: o listener HTTP responde com um redirecionamento, e um POST redirecionado não entrega nenhuma notificação.
Tipo de autenticaçãoBearerX-Api-Key não deve ser usado. Esse header é a credencial REST do próprio Bulk Signer, e uma notificação que o apresenta é recusada.
Token de AutenticaçãoO valor de Signer__WebhookSecretSem a palavra Bearer. O Signer acrescenta o prefixo.

O Signer entrega todo evento da organização a todo webhook da organização. O Bulk Signer age sobre DocumentsCreated, DocumentSigned e DocumentApproved e responde 204 a todo outro evento. O Signer tenta de novo uma entrega que não recebe uma resposta 2xx (Webhooks).

3. Verificação. Crie um documento como no passo 6. Ele é assinado em segundos, e a verificação signer-notifications informa accepted; the last arrived at this instance at <hora>. Com o webhook em funcionamento, Signer__FolderSweepIntervalSeconds pode voltar ao padrão de 300.

Login pelo Microsoft Entra ID (opcional)​

Por padrão, a página de login do dashboard pede a Auth__ApiKey. Com uma seção Auth:EntraId, ela oferece Entrar com a Microsoft no lugar, e dois app roles controlam o acesso: Administrator para o dashboard do operador e Approver para as páginas do aprovador (Configuração). Esta implantação usa somente Administrator. Exige a seção HTTPS: a Microsoft só aceita uma URI de redirecionamento https para um host que não seja localhost.

EfeitoEspecificação
O formulário de login com a chave de APIRemovido da página de login.
O X-API-Key da API RESTInalterado. A Auth__ApiKey continua obrigatória.
Sessões criadas com a chave de APIDeixam de funcionar quando o container reinicia com a seção.
SaídaEncerra somente a sessão do Bulk Signer. A sessão da Microsoft permanece.

1. O registro de aplicativo. Dê ao ambiente um registro próprio. New-BulkSignerEntraApp.ps1, executado de qualquer estação de trabalho com o PowerShell 7, cria um registro de tenant único com a URI de redirecionamento https://<host>/signin-oidc, os dois app roles, a claim email e um aplicativo empresarial com Assignment required:

pwsh ./New-BulkSignerEntraApp.ps1 -BaseUrl https://<host> -DisplayName "Lacuna Bulk Signer"

Ao final, o script imprime, uma única vez, o bloco Auth__EntraId__TenantId, Auth__EntraId__ClientId e Auth__EntraId__ClientSecret. Para criar o registro manualmente, siga Login pelo Microsoft Entra ID em Instalação.

2. Atribua as pessoas. No Entra admin center, em Enterprise applications → o aplicativo → Users and groups, atribua o app role Administrator a cada operador. Uma conta sem atribuição não consegue entrar, e uma conta que se autentica sem nenhum dos dois roles é recusada.

3. A configuração. O client secret é lido a partir de um prompt que não o exibe:

read -rsp 'Client secret: ' VALUE; echo
sudo tee -a .env > /dev/null <<EOF
Auth__EntraId__TenantId='<o valor de Auth__EntraId__TenantId>'
Auth__EntraId__ClientId='<o valor de Auth__EntraId__ClientId>'
Auth__EntraId__ClientSecret='$VALUE'
EOF
unset VALUE
sudo nano .env # substitua os dois marcadores
sudo docker compose up -d

As três chaves são exigidas em conjunto: uma seção preenchida pela metade interrompe o container no boot, e o log cita a chave que falta.

4. Verificação. Siga o primeiro redirecionamento do login sem entrar:

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

A URL deve apontar para login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize, com o ID do aplicativo e redirect_uri=https%3A%2F%2F<host>%2Fsignin-oidc. O esquema https é o valor a confirmar: http significa que os headers encaminhados da seção HTTPS não estão em vigor.

ItemDescrição
Expiração do client secretO tempo de vida padrão do script é de doze meses. Um secret expirado só falha no login, com um erro AADSTS. Crie um novo secret no registro, substitua Auth__EntraId__ClientSecret no .env e execute sudo docker compose up -d.
RemoçãoRemova as três linhas Auth__EntraId__ do .env e execute sudo docker compose up -d. O login com a chave de API volta.

Operação​

Todo comando é executado em $DIR. Uma alteração no .env ou no arquivo do Compose entra em vigor com sudo docker compose up -d, que recria o container.

OperaçãoProcedimentoObservações
AtualizaçãoFaça o backup, pause o pipeline (POST /api/pipeline/pause), espere até nenhum job estar Processing ou Verifying, altere a versão na linha image:, execute sudo docker compose pull && sudo docker compose up -d, e retome (POST /api/pipeline/resume).As migrações são executadas no boot. Um container interrompido durante uma assinatura faz o próximo boot perguntar ao Signer como o job terminou, e alguns desses jobs terminam Failed com signer-folder.interrupted (Integração com o Lacuna Signer). A varredura continua com o pipeline pausado.
Backupsudo docker compose stop, depois arquive data/, config/, .env e docker-compose.yml, depois sudo docker compose start.O arquivo contém o certificado, a senha criptografada dele e a chave que a descriptografa. Armazene-o como o próprio certificado, fora da máquina virtual.
Rotação do segredo do webhookSubstitua Signer__WebhookSecret no .env, execute sudo docker compose up -d, e depois informe o novo valor no webhook no Signer.Entre as duas alterações, as notificações recebem 401; o Signer as tenta de novo e a varredura detecta os documentos restantes.
Rotação da chave de API do SignerCrie a nova chave no Signer, substitua Signer__ApiKey no .env, execute sudo docker compose up -d, e só então revogue a chave anterior.Com uma chave revogada, toda varredura falha, e a verificação signer-folder-sweep falha depois de três passagens seguidas com falha.
Renovação do certificadoPause o pipeline. Substitua config/signing.pfx (com o dono e as permissões do passo 4.4) e, se a senha mudou, informe-a na página do perfil, em Editar certificado. Reinicie com sudo docker compose restart e retome.O certificado é lido no boot. Se o novo certificado contiver um CPF diferente, os documentos pendentes no Signer para o CPF anterior não têm ação para o novo titular; cada um é registrado uma vez como Failed com signer-folder.no-holder-action.
Troca de pastaSalve a nova pasta na página do perfil.Entra em vigor sem reinício. A seção SignerFolder do appsettings.Production.json não é lida de novo.
Remoçãosudo docker compose down, remova o webhook no Signer e sudo docker logout $REGISTRY.data/, config/ e .env permanecem em $DIR até serem excluídos.

Referência de erros​

Código ou mensagemOrigemSignificadoSolução
permission denied em /var/lib/bulksigner ou em /etc/bulksigner/signing.pfxLog do container, no bootOs diretórios montados ou o PFX não pertencem ao UID 1654.Repita o passo 4.4.
authentication required no docker pullDockerSem docker login.Repita o passo 3 com as credenciais emitidas pela Lacuna.
not found no docker pullDockerUm REPOSITORY ou uma VERSION que não existe, ou credenciais que não enxergam o repositório.Confira as variáveis de shell e as credenciais emitidas pela Lacuna.
did not open with the PKCS#12 password given (IncorrectPinException), com o perfil degradadoLog do container e verificação signing-profile:signer-folder, no bootA senha não abre config/signing.pfx: uma senha errada, ou outro arquivo. Corrigir o .env não tem efeito depois do primeiro boot, porque a senha já foi importada para o banco.Confira com o openssl do passo 4.4. Uma senha errada: informe a correta na página do perfil, em Editar certificado, e execute sudo docker compose restart. Um arquivo errado: substitua-o como na Renovação do certificado (Operação).
Uma linha de log que cita Signing:ProfileSecretsKeyLog do container, primeiro bootA importação armazenaria a senha do PFX sem a chave.Defina Signing__ProfileSecretsKey (passo 4.2).
Uma linha de log que cita Signer:Endpoint ou Signer:ApiKeyLog do container, no bootUma chave em Signer: está definida sem essas duas.Complete o .env e o appsettings.Production.json (passos 4.2 e 4.3).
Uma linha de log que cita Signer:WebhookSecretLog do container, no bootO segredo tem menos de 32 caracteres, ou espaços no início ou no fim.Gere-o como na seção do webhook.
Uma linha de log que cita as duas chaves de headers encaminhadosLog do container, no bootASPNETCORE_FORWARDEDHEADERS_ENABLED e Hosting__ForwardedHeaders__Enabled estão definidas.Mantenha somente Hosting__ForwardedHeaders__*.
signer-notification.unauthorizedRota de notificações, 401O token cadastrado no Signer difere do segredo, foi informado com a palavra Bearer, ou o tipo de autenticação não é Bearer.Corrija o webhook no Signer.
signer-notification.not-configuredRota de notificações, 404O container não recebeu a Signer__WebhookSecret.Verifique o .env e execute sudo docker compose up -d.
signer-folder.no-holder-actionJob, FailedO documento está na pasta vinculada, mas não tem ação de assinatura para o CPF do certificado.Inclua o titular como signatário com o CPF. A próxima varredura detecta a nova ação. Não admite nova tentativa.
signer-folder.signature-refusedJob, FailedO Signer recusou a assinatura; os resultados da validação dele estão no histórico do job. A causa usual é o certificado (revogado, expirado ou que não é o do participante).Corrija a causa informada pelo Signer e faça uma nova tentativa do job.
signer-folder.interruptedJob, FailedO container parou durante a assinatura.Verifique o documento no Signer e faça uma nova tentativa do job. A nova tentativa termina Canceled se a ação do titular já estiver concluída.
AADSTS50011Microsoft Entra ID, no loginA URI de redirecionamento enviada é http://…, ou não corresponde ao registro de aplicativo.Verifique os headers encaminhados da seção HTTPS e a URI https://<host>/signin-oidc do registro.

Um job que termina Canceled não traz código: o documento foi cancelado, recusado ou expirou no Signer, ou já tinha sido assinado pelo titular, antes de o container assiná-lo. Isso não é uma falha. Todo código signer-folder.* está especificado em Solução de problemas.

Sintomas​

SintomaCausaSolução
O perfil está degradado, com um motivo sobre o CPF do certificado.O certificado não contém CPF.Use um e-CPF ou um e-CNPJ da ICP-Brasil. Veja Solução de problemas.
A verificação signer-folder-sweep falha.Três passagens seguidas falharam. A causa usual é uma Signer:ApiKey incorreta, ou um Signer:Endpoint que não é o endereço da API.Veja Solução de problemas.
Um documento nunca é detectado.O documento está em uma subpasta, o titular foi incluído sem o CPF do certificado, ou a ação pendente é de outro participante.Corrija o documento no Signer. Um documento cuja vez ainda não chegou é detectado quando ela chega.
signer-notifications informa que nenhuma notificação chegou depois de um documento ser criado.O Signer não acessa https://<host>: uma URL incorreta, http://, ou um firewall que não libera a porta 443.Corrija a URL no Signer ou o firewall.
Os documentos são assinados, mas até um minuto depois de criados.A notificação não chega, e os documentos são detectados pela varredura.Veja Solução de problemas.

Limitações​

Não oferecidoAlternativa
Um arquivo assinado na máquina virtualO Signer armazena o documento. Baixe-o do Signer; nada é gravado em output/.
Verificação do resultado pelo Bulk SignerNenhuma. A verificação fica desabilitada neste método, porque o Signer valida a assinatura ao incorporá-la ao documento.
Mais de uma instânciaAzure App Service (modo cluster).
A direção oposta: um arquivo enviado ao Signer para uma pessoa assinarO método LacunaSigner, que usa os mesmos Signer:Endpoint e Signer:ApiKey e é escolhido por perfil. Veja Integração com o Lacuna Signer.
Ver em Markdown