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.
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.
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
Conexões
| Direção | Conteúdo | Credencial |
|---|---|---|
| Container → Signer | A varredura, a releitura de cada documento, e o início e a conclusão de cada assinatura | Signer:ApiKey, enviada como X-Api-Key |
| Signer → nginx → container | O webhook, quando configurado: POST https://<host>/api/signer/notifications | Signer:WebhookSecret, enviado como Authorization: Bearer |
| Operador → nginx → container | O dashboard e a API REST | Auth:ApiKey, ou uma sessão do Microsoft Entra ID |
| Máquina virtual → registry da Lacuna | O download da imagem | As 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
| Aspecto | Comportamento com o método SignerFolder |
|---|---|
| Conteúdo do documento | Nenhum 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 titular | O 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 assinatura | O 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. |
| Descoberta | Uma 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
| Requisito | Especificação |
|---|---|
| Máquina virtual | Ubuntu 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 registry | As 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ça | A licença do PKI SDK. Veja Obtendo a licença do PKI SDK. |
| Organização no Lacuna Signer | Uma 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 Signer | Uma chave de API dessa organização (passo 1.2). |
| Material de assinatura | O 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 titular | O 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ável | Conteúdo |
|---|---|
REGISTRY | Somente o host do registry, por exemplo <nome>.azurecr.io. É o argumento do docker login, que não aceita um caminho. |
REPOSITORY | O caminho da imagem dentro do registry, por exemplo lacuna/bulksigner. |
VERSION | A versão a instalar, por exemplo 2.20.1. Use uma versão explícita, não latest. |
SIGNER | O endereço da API do Lacuna Signer (passo 1.1), sem barra no final. |
HOST | O hostname público da implantação. Usado somente a partir da seção HTTPS. |
DIR | O 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.
| Propriedade | Especificação |
|---|---|
| Acesso ao menu Aplicações | Restrito 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ção | A chave é exibida uma única vez, na criação. |
| Escopo | A organização em que foi criada. O container lê os documentos com essa chave. |
| Acesso exigido | Um 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.
| Regra | Especificação |
|---|---|
| Vínculo | De um para um. Dois perfis não podem compartilhar uma pasta. |
| Alcance | A 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 Signer | Onde a configuração é definida |
|---|---|
| On-premises | Nas configurações da instância. |
| Nuvem da Lacuna | Pela 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.
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:
| Arquivo | Conteúdo |
|---|---|
docker-compose.yml | O container, as montagens e a rede dele. |
.env | Os segredos, como variáveis de ambiente. Legível somente pelo root. |
config/appsettings.Production.json | O perfil de assinatura e a conexão com o Signer. Não contém segredo. |
config/signing.pfx | O 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
| Elemento | Especificação |
|---|---|
image | A versão de VERSION. Uma atualização altera esta linha (Operação). |
ports | HTTP simples na porta 8080. A seção HTTPS a restringe a 127.0.0.1. |
./data | O 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.pfx | Lido a cada boot. Deve permanecer neste caminho enquanto o perfil o usar. |
networks | Uma 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ável | Descrição |
|---|---|
Signing__PkiSdkLicense | A licença do PKI SDK. |
Signing__ProfileSecretsKey | Criptografa 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__Password | A senha do PFX, importada para o perfil no primeiro boot. |
Signer__ApiKey | Enviada como X-Api-Key em toda chamada ao Signer. |
Auth__ApiKey | A 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.
Signing__ProfileSecretsKey fora da máquina virtualCopie-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ção | Especificaçã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. |
Name | signer-folder. Não pode ser default e não pode ser alterado depois da importação. |
Format | Exigido pela configuração, ignorado pelo método: o Signer escolhe o formato. |
Verify, ValidateCertificate | Devem ser false; o padrão das duas é true. O Signer valida o certificado e a assinatura. |
SignerFolder:Id | A pasta do passo 1.3. Name é exibido somente na página do perfil. |
Signer:Endpoint | O endereço da API do Signer. Junto com Signer:ApiKey, obrigatório assim que qualquer chave em Signer: é definida. |
Signer:FolderSweepIntervalSeconds | O 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:
| Aviso | Quando | Motivo |
|---|---|---|
Watched folder 'default' is unassigned | A cada boot | Nenhum perfil recebe arquivos de uma pasta monitorada. |
The migration operation 'PRAGMA foreign_keys = 0;' … cannot be executed in a transaction | No primeiro boot | O Entity Framework informa uma migração que não pode ser executada em uma transação. |
No XML encryptor configured | No primeiro boot, e quando uma nova chave de sessão é criada | O 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 boot | A 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.1 | Um 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ção | Resultado esperado |
|---|---|
/api/health | "status":"healthy" |
| O perfil | "method": "SignerFolder", "degraded": false |
signer-folder-sweep | ok: true. A primeira passagem é feita no boot: the last pass at this instance finished without a failure at … |
signer-notifications | not accepted (Signer:WebhookSecret is not set) até o webhook ser configurado. |
pki-license | loaded |
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:
- Selecione Novo documento, faça upload de um PDF e selecione a organização e a pasta vinculada.
- 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.
- 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:
| Status | Significado |
|---|---|
| Na fila | O documento foi detectado e o job foi criado. |
| Processando | O container releu o documento, iniciou a assinatura e assinou o hash com a chave do PFX. |
| Verificando | A assinatura foi entregue ao Signer, que a valida e a incorpora ao documento. |
| Concluído | O 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ção | Efeito |
|---|---|
127.0.0.1:8080:8080 | A porta 8080 deixa de ser acessível de fora da máquina virtual, independentemente do ufw. |
Hosting__ForwardedHeaders__Enabled | Lê 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__0 | Confia 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:
- Abra Organizações e selecione a organização.
- 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.
- Preencha os campos conforme especificado abaixo e selecione Salvar.
| Campo | Valor | Requisito |
|---|---|---|
| URL | https://<host>/api/signer/notifications | O esquema deve ser https: o listener HTTP responde com um redirecionamento, e um POST redirecionado não entrega nenhuma notificação. |
| Tipo de autenticação | Bearer | X-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ção | O valor de Signer__WebhookSecret | Sem 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.
| Efeito | Especificação |
|---|---|
| O formulário de login com a chave de API | Removido da página de login. |
O X-API-Key da API REST | Inalterado. A Auth__ApiKey continua obrigatória. |
| Sessões criadas com a chave de API | Deixam de funcionar quando o container reinicia com a seção. |
| Saída | Encerra 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.
| Item | Descrição |
|---|---|
| Expiração do client secret | O 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ção | Remova 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ção | Procedimento | Observações |
|---|---|---|
| Atualização | Faç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. |
| Backup | sudo 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 webhook | Substitua 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 Signer | Crie 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 certificado | Pause 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 pasta | Salve 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ção | sudo 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 mensagem | Origem | Significado | Solução |
|---|---|---|---|
permission denied em /var/lib/bulksigner ou em /etc/bulksigner/signing.pfx | Log do container, no boot | Os diretórios montados ou o PFX não pertencem ao UID 1654. | Repita o passo 4.4. |
authentication required no docker pull | Docker | Sem docker login. | Repita o passo 3 com as credenciais emitidas pela Lacuna. |
not found no docker pull | Docker | Um 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 degradado | Log do container e verificação signing-profile:signer-folder, no boot | A 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:ProfileSecretsKey | Log do container, primeiro boot | A 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:ApiKey | Log do container, no boot | Uma 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:WebhookSecret | Log do container, no boot | O 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 encaminhados | Log do container, no boot | ASPNETCORE_FORWARDEDHEADERS_ENABLED e Hosting__ForwardedHeaders__Enabled estão definidas. | Mantenha somente Hosting__ForwardedHeaders__*. |
signer-notification.unauthorized | Rota de notificações, 401 | O 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-configured | Rota de notificações, 404 | O container não recebeu a Signer__WebhookSecret. | Verifique o .env e execute sudo docker compose up -d. |
signer-folder.no-holder-action | Job, Failed | O 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-refused | Job, Failed | O 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.interrupted | Job, Failed | O 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. |
AADSTS50011 | Microsoft Entra ID, no login | A 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
| Sintoma | Causa | Soluçã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 oferecido | Alternativa |
|---|---|
| Um arquivo assinado na máquina virtual | O Signer armazena o documento. Baixe-o do Signer; nada é gravado em output/. |
| Verificação do resultado pelo Bulk Signer | Nenhuma. A verificação fica desabilitada neste método, porque o Signer valida a assinatura ao incorporá-la ao documento. |
| Mais de uma instância | Azure App Service (modo cluster). |
| A direção oposta: um arquivo enviado ao Signer para uma pessoa assinar | O método LacunaSigner, que usa os mesmos Signer:Endpoint e Signer:ApiKey e é escolhido por perfil. Veja Integração com o Lacuna Signer. |