---
title: "Configuração da estação de trabalho"
description: "Todas as configurações do Workstation Service do TrustBridge e como uma instalação na frota as fornece; o Tray App não tem arquivo de configuração."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# Configuração da estação de trabalho

Todas as configurações que o Workstation Service aceita e como uma instalação na frota as fornece. As
configurações do Servidor estão em [Configuração do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/configuration); os dois hosts não
compartilham nenhuma configuração. **O Tray App não tem nenhum arquivo de configuração** (veja a
[última seção](https://docs.lacunasoftware.com/articles/trustbridge/workstation-configuration#o-tray-app-não-lê-nenhum-arquivo-de-configuração)).

Todo valor aqui tem um padrão, e **a maioria das máquinas da frota não altera nenhum deles**. Três
valores chegam pelo MSI e pela Diretiva de Grupo; os demais ficam no arquivo de configuração que o MSI
instala ao lado dos binários.

## Como um valor chega a uma máquina

A última fonte a definir uma chave prevalece:

| | Fonte | O que a fornece |
|---|---|---|
| 1 | `appsettings.json` ao lado dos binários | Instalado pelo MSI em `Program Files`. Nada no serviço o regrava. |
| 2 | `appsettings.Development.json`, user secrets | Somente a execução de um desenvolvedor no console. |
| 3 | `HKLM\Software\TrustBridge`, a **preferência** | O MSI, a partir de `SERVER_URL`, `PKI_LICENSE` e `INSTALLER_KEY`. Um reparo ou uma gravação manual com elevação grava os mesmos valores no mesmo lugar. |
| 4 | Variáveis de ambiente, `__` no lugar de `:` | Uma execução no console ou um wrapper de serviço. Não é assim que uma instalação na frota funciona. |
| 5 | Argumentos de linha de comando | Somente uma execução no console. |
| 6 | `HKLM\Software\Policies\TrustBridge`, a **diretiva** | A Diretiva de Grupo, por meio do modelo ADMX fornecido. Somente o mecanismo de diretivas pode gravar ali. |

Três valores chegam pelo Registro: `ServerUrl` vira `Server:Url`, `PkiLicense` vira
`Certificates:Validation:License` e `InstallerKey` vira `Server:InstallerKey`. Um valor publicado com
o tipo de Registro errado (um `REG_DWORD` onde se esperava uma string) **impede a inicialização,
citando o local**. **Os dois locais do Registro são lidos uma vez, na inicialização**: uma atualização
de GPO entra em vigor na próxima inicialização do serviço.

**Não há segredo que uma instalação entregue a uma máquina para que ela entre na plataforma.** Uma
máquina gera a própria Chave da Estação de Trabalho, se anuncia e aguarda ser **admitida** por um
Administrador. Nada nesta página é enviado pelo Servidor; a única coisa que o Servidor envia a uma
máquina é o conjunto de Autoridades Certificadoras Confiáveis dele, que é política de confiança, e não
configuração.

Os formatos de valor são os do Servidor: `:` em um arquivo e `__` no ambiente, durações como
`[d.]hh:mm:ss`, com a armadilha dos vinte e quatro dias, e tamanhos como inteiros simples.

## Acessando o Servidor

```json
{
  "Server": {
    "Url": "https://trustbridge.example.com",
    "InstallerKey": "MIGHAgEAMBMGByqGSM49…",
    "InitialReconnectDelay": "00:00:01",
    "MaxReconnectDelay": "00:01:00"
  }
}
```

### `Server:Url`

**Padrão** não definido · **Instalação na frota** o MSI grava `SERVER_URL` em `HKLM\Software\TrustBridge\ServerUrl`; a Diretiva de Grupo o sobrepõe em `HKLM\Software\Policies\TrustBridge\ServerUrl` · **Valor inválido** impede a inicialização

Onde fica o Servidor desta máquina. **Obrigatório, e precisa ser um URI absoluto.** O MSI recusa
primeiro um valor vazio ou sem esquema, na condição de inicialização dele; a verificação do serviço na
inicialização é a segunda barreira. O Tray App mostra essa URL e nunca pode defini-la: quem a grava
decide onde a máquina pede para ser admitida, então a gravação fica atrás de uma barreira de elevação.

### `Server:InstallerKey`

**Padrão** a chave do próprio produto · **Instalação na frota** o MSI grava `INSTALLER_KEY` em `HKLM\Software\TrustBridge\InstallerKey`, somente em uma implantação que gerou uma chave própria · **Valor inválido** impede a inicialização

A Installer Key com que esta máquina assina a requisição de admissão, além da própria chave: PKCS#8
DER em base64, ECDSA P-256. Ela mostra que a requisição veio do produto genuíno e **não autentica
nada**; toda cópia do TrustBridge tem a metade privada do produto. Uma implantação que queira uma
chave própria configura a metade pública no Servidor, em `Admission:InstallerKeys`, e entrega a
metade privada aqui. Defina-a nas máquinas **antes** que o Servidor deixe de confiar na chave antiga.
Não é um segredo. Fica de fora do modelo ADMX, de propósito.

### `Server:InitialReconnectDelay` e `Server:MaxReconnectDelay`

**Padrão** 1 s e 1 min · **Instalação na frota** nunca alterados · **Valor inválido** um valor não positivo, ou um teto abaixo do piso, impede a inicialização

Onde começa o backoff de reconexão depois que o canal cai, e o teto até onde ele sobe. **Uma máquina
que não consegue acessar o Servidor tenta de novo nesse ritmo indefinidamente.** Duas falhas são
registradas no log em `Error`, para que possam ser distinguidas de uma instabilidade passageira: o
Servidor respondeu 401 no canal (admissão retirada ou revogada), e o Servidor recusou a requisição de
admissão (revogada, Installer Key não confiável, requisições demais do endereço ou fila cheia; o log
cita as quatro). Aguardar a admissão não é uma falha e é registrado uma vez em `Information`.

## Detecção de certificados

```json
{
  "Certificates": {
    "SweepInterval": "00:01:00",
    "ValidationInterval": "01:00:00",
    "ChangeDebounce": "00:00:02"
  }
}
```

| Chave | Padrão | Significado |
|---|---|---|
| `Certificates:SweepInterval` | 1 min | A varredura de reconciliação, sempre ativa: uma enumeração com comparação de todos os repositórios, que cobre um gatilho de mudança perdido ou um token que nunca aparece como smart card. Um valor não positivo impede a inicialização. |
| `Certificates:ValidationInterval` | 1 h | A frequência com que todo certificado presente é validado de novo por completo, para que uma revogação, uma expiração ou o fim de uma janela de tolerância apareça dentro de um intervalo. |
| `Certificates:ChangeDebounce` | 2 s | Quanto tempo o pipeline aguarda depois de um sinal de mudança antes de enumerar, para que a chegada de um cartão seja agrupada e o middleware tenha tempo de tornar os certificados legíveis. Fora do intervalo de zero a 5 minutos, impede a inicialização. Um valor baixo demais custa uma varredura inteira; um alto demais custa um segundo de latência. |

## Os repositórios de certificados

```json
{
  "Certificates": {
    "WindowsStore": { "Enabled": true },
    "Pkcs11": { "Modules": "C:\\Windows\\System32\\eTPKCS11.dll;C:\\Vendors\\uncommon-p11.dll" }
  }
}
```

### `Certificates:WindowsStore:Enabled`

**Padrão** `true` · **Instalação na frota** decisão do administrador · **Valor inválido** impede a inicialização

Se o repositório de certificados do Windows da máquina (`LocalMachine\My`) é lido em busca de
certificados A1. Ligado, um A1 instalado ali é enumerado, validado e anunciado como qualquer outro
certificado, com o leitor ignorando tudo o que não seja uma identidade de assinatura (sem chave
privada, ou sem CPF de e-CPF). A notificação de mudanças do repositório fica aberta, para que uma
importação seja anunciada dentro de `ChangeDebounce`. Desligado, nada na máquina abre esse
repositório. Lido uma vez, na inicialização.

Um certificado A1 é anunciado e fica visível no Tray App, mas uma Sessão de Assinatura sobre ele ainda
espera um PIN que nenhum A1 tem; por isso, sessões e assinaturas com um Certificado de Estação de
Trabalho A1 são recusadas até que o fluxo sem PIN seja lançado. Um A1 importado no Cofre de
Certificados é, hoje, a forma suportada de assinar com um deles.

### `Certificates:Pkcs11:Modules`

**Padrão** não definido, o que significa a lista de fabricantes fornecida · **Instalação na frota** nunca alterado em uma máquina com middleware comum · **Valor inválido** um módulo que não carrega é uma falha desse repositório no log, e não uma inicialização recusada

Os módulos PKCS#11 dos fabricantes, por meio dos quais os tokens A3 são lidos, como **uma única
string de caminhos absolutos separados por ponto e vírgula**. Três estados:

- **Não definido** é a lista padrão fornecida: SafeNet Authentication Client, SafeSign IC, Watchdata
  PROTON, Feitian ePass2003, Idemia AWP e Thales IDPrime, nos caminhos em que esses fabricantes os
  instalam, verificados pela existência do arquivo. **Frotas comuns têm detecção de tokens sem
  nenhuma configuração.**
- **Definido** é exatamente o que está na lista, por inteiro; nada é verificado e nenhum padrão é
  mantido. É assim que se adiciona um middleware incomum, ao custo de também listar os comuns de que a
  máquina precisa.
- **Definido como vazio** desliga a detecção de A3. Por variável de ambiente, desligado é
  `Certificates__Pkcs11__Modules=";"`, porque uma variável que não existe é lida como não definida.

Cada módulo é um repositório próprio e eles falham isoladamente: um middleware com falha custa apenas
os certificados daquele fabricante, que passam a `STALE` ao longo da janela de tolerância. A
enumeração nunca envolve um PIN e não consome nada do contador de tentativas de um token. Lido uma
vez, na inicialização.

## Validação de certificados e a licença do PKI SDK

O mesmo nome de seção e a mesma política que o Servidor lê. Quatro coisas são diferentes em uma
estação de trabalho, e cada uma é destacada abaixo.

```json
{
  "Certificates": {
    "Validation": {
      "License": "PD94bWwgdmVyc2lvbj0…",
      "UseIcpBrasil": true,
      "UseMachineRootStore": false,
      "UseLacunaTestPki": false,
      "UseServerTrustedCas": true,
      "TrustedRootPaths": ["C:\\ProgramData\\TrustBridge\\anchors\\your-root.pem"],
      "RevocationGraceWindow": "1.00:00:00",
      "RevocationTimeout": "00:00:05",
      "CheckTimeout": "00:00:30"
    }
  }
}
```

### `Certificates:Validation:License`

**Padrão** não definido · **Instalação na frota** o MSI grava `PKI_LICENSE` em `HKLM\Software\TrustBridge\PkiLicense`; a Diretiva de Grupo o sobrepõe em `HKLM\Software\Policies\TrustBridge\PkiLicense` · **Valor inválido** uma licença vencida ou corrompida gera uma linha `Critical` na inicialização; um valor de Registro do tipo errado impede a inicialização

**Obrigatória em todas as máquinas, e essa é a primeira diferença em relação ao Servidor.** Aqui, o
SDK é o que lê qualquer certificado; sem licença, **todo certificado da máquina aparece como
`UNTRUSTED`** e a máquina não assina nada. O valor é a própria licença, codificada em base64 em uma
linha, e não um caminho. O local da diretiva está no modelo ADMX de propósito: um vencimento da
licença seria, de outra forma, uma indisponibilidade da frota, e uma atualização de GPO é como uma
renovação chega à frota, com cada máquina adotando-a na próxima inicialização do serviço.

### As fontes de âncoras

| Chave | Padrão | Significado |
|---|---|---|
| `Certificates:Validation:UseIcpBrasil` | `true` | As raízes da ICP-Brasil que o SDK traz. Desligá-la é uma decisão de confiança. |
| `Certificates:Validation:UseMachineRootStore` | `false` | **A segunda diferença: aqui ela tem efeito.** Confia em todas as ACs públicas do programa de raízes do Windows, um conjunto muito mais amplo que a ICP-Brasil. |
| `Certificates:Validation:UseLacunaTestPki` | `false` | Confia também na PKI de testes da Lacuna. **Somente para desenvolvimento**: a Lacuna publica as chaves privadas correspondentes. O serviço avisa isso em `Critical` a cada inicialização. |

### `Certificates:Validation:UseServerTrustedCas`

**Padrão** `true` · **Instalação na frota** o arquivo de configuração que o MSI instala (esta chave não tem valor no Registro, então nenhuma GPO a alcança) · **Valor inválido** impede a inicialização

**A terceira diferença: esta chave só tem efeito em uma máquina.** Define se a máquina incorpora as
**Autoridades Certificadoras Confiáveis** do Servidor ao próprio conjunto de âncoras. Ligada, a
máquina pede o conjunto ao Servidor depois de cada handshake e pede de novo quando o Servidor avisa
que ele mudou; assim, uma AC que um Administrador adiciona na tela **Autoridades Certificadoras
Confiáveis** chega aos vereditos desta máquina em segundos. O último conjunto recebido fica em cache
localmente e continua valendo enquanto o Servidor estiver inacessível: um Servidor que não responde
não disse nada, e só um Servidor respondendo, inclusive respondendo *nenhuma Autoridade Certificadora
Confiável*, substitui o que a máquina tem.

**Enquanto esta máquina tiver um conjunto não vazio recebido do Servidor, `TrustedRootPaths` é
totalmente desconsiderado**, e o serviço avisa isso em `Critical`, citando os caminhos descartados. Um
controle que só acrescentasse confiança nunca conseguiria retirá-la.

Desligada, a máquina nunca pede e valida apenas contra a própria configuração, `TrustedRootPaths`
incluído: é a postura para uma frota com um pipeline próprio de âncoras, sob controle de mudanças.
Desligá-la em toda a frota é uma alteração no arquivo de configuração de cada máquina, e vale a pena
planejá-la **antes** de atualizar o Servidor para o protocolo 2, e não depois. De qualquer forma, a
máquina informa em qual postura está a cada conexão, e a tela **Estações de Trabalho** a mostra por
máquina.

### `Certificates:Validation:TrustedRootPaths`

**Padrão** vazio · **Instalação na frota** decisão do administrador, implantada junto com os arquivos de âncora · **Valor inválido** um arquivo ilegível gera uma linha `Critical`, e não uma inicialização recusada

Como uma AC privada é adicionada a partir de um arquivo nesta máquina. **Não é mais a palavra
final**: a forma suportada de confiar em uma AC privada em toda a frota é uma Autoridade Certificadora
Confiável adicionada uma vez no Servidor. Esta chave ainda decide a resposta inteira em uma máquina em
que `UseServerTrustedCas` está desligado, em uma que nunca teve contato com um Servidor, em uma cujo
Servidor não tem Autoridades Certificadoras Confiáveis ou em uma que ainda está no protocolo 1.

**A quarta diferença: estes precisam ser caminhos absolutos.** Quem consegue adicionar um arquivo aqui
consegue fazer um certificado próprio ser validado como `ACTIVE`, então os arquivos devem ficar em
`C:\ProgramData\TrustBridge\anchors\`, cuja ACL pertence ao instalador. Sem nenhuma âncora, o serviço
ainda inicia e todo certificado aparece como `UNTRUSTED`, com uma linha `Critical` citando as
configurações; arquivos de âncora que contêm só intermediárias geram uma segunda linha, diferente.

### Os limites de revogação

| Chave | Padrão | Significado |
|---|---|---|
| `Certificates:Validation:RevocationGraceWindow` | 24 h (`1.00:00:00`) | Por quanto tempo a última verificação de revogação bem-sucedida mantém um certificado `ACTIVE` enquanto a AC dele está inacessível; depois disso, o certificado passa a `STALE`. Ampliar este valor é ampliar o tempo durante o qual um certificado revogado continua assinando enquanto a AC dele está inacessível. Um valor negativo impede a inicialização. |
| `Certificates:Validation:RevocationTimeout` | 5 s | Quanto tempo o download de uma LCR ou a busca de um emissor pode levar antes de a AC ser considerada inacessível. Um valor não positivo impede a inicialização. |
| `Certificates:Validation:CheckTimeout` | 30 s | O limite externo da verificação inteira de um certificado. As validações são feitas em série na máquina, então uma verificação sem limite trava todos os certificados atrás dela. Zero espera indefinidamente. |

### Enquanto o Servidor e esta máquina estão em versões diferentes

`UseServerTrustedCas` só tem efeito em um canal no **protocolo 2**, e um Servidor e uma frota nunca
são atualizados no mesmo minuto. A ordem de atualização é **primeiro o Servidor, depois as estações de
trabalho, dentro de um mesmo ciclo de versão**, e ela tem consequências:

- **Um Servidor à frente desta máquina se conecta e simplesmente nunca pede.** Uma máquina no
  protocolo 1 faz o handshake, assina e informa vereditos como sempre fez, e continua validando contra
  o próprio `TrustedRootPaths`. Uma Autoridade Certificadora Confiável adicionada no Servidor não
  chega a ela, e a tela **Estações de Trabalho** mostra *Requer atualização* na linha dela.
- **Esta máquina à frente do Servidor não se conecta.** O Servidor mais antigo recusa o handshake
  (*Protocol version 2 is newer than this server's supported window (0–1); update the Server
  first*), e esta máquina **não consegue assinar** até que o Servidor seja atualizado.

## O canal entre o Service e o Tray

O canal por named pipe entre o serviço e o Tray App. A ACL dele admite usuários interativos, e esse é
todo o controle de acesso dele. **Uma instalação na frota não mexe em nada disto.**

```json
{
  "Tray": {
    "PipeName": "TrustBridge.WorkstationService",
    "PromptTimeout": "00:01:30",
    "MaxConsecutivePinFailures": 3,
    "PinFailureCooldown": "00:05:00",
    "LogBufferSize": 500
  }
}
```

| Chave | Padrão | Significado |
|---|---|---|
| `Tray:PipeName` | `TrustBridge.WorkstationService` | O pipe em que o serviço escuta. Configurável só para que um desenvolvedor possa executar uma segunda instância; o Tray App se conecta ao nome conhecido e não tem configuração própria. Um valor em branco impede a inicialização. |
| `Tray:PromptTimeout` | 90 s | Quanto tempo uma solicitação de PIN fica na tela do usuário antes de o serviço desistir dela. **Deliberadamente mais folgado que o `Sessions:PinPromptTimeout` do Servidor (60 s), e precisa continuar assim**: um Servidor que desistiu não consegue mandar esta máquina fechar a solicitação, então é esta janela que encerra toda solicitação não respondida. |
| `Tray:MaxConsecutivePinFailures` | 3 | Quantos PINs um token pode rejeitar seguidamente antes que as entradas para aquele certificado sejam recusadas sem ser repassadas. Limita um processo que tenta milhares de vezes, não uma pessoa: o usuário ainda pode bloquear o próprio token digitando errado. Zero impede a inicialização. |
| `Tray:PinFailureCooldown` | 5 min | Por quanto tempo as entradas para um certificado são recusadas depois que esse limite é atingido. Não é um estado do token; nenhum PUK está envolvido. |
| `Tray:LogBufferSize` | 500 | Quantas entradas recentes de log o serviço guarda para o painel de diagnóstico do Tray. Somente em memória. |

## O Cache de PIN

**Local e controlado pelo administrador.** O Servidor não envia nada para cá, e nenhuma chamada do
Tray ou da API pode alterá-lo. Uma linha a cada inicialização informa em qual postura a máquina está.

```json
{
  "PinCache": {
    "SurviveRestart": false,
    "Ttl": "08:00:00",
    "SweepInterval": "00:05:00",
    "StorePath": "C:\\ProgramData\\TrustBridge\\pin-cache.dat",
    "KeyRingPath": "C:\\ProgramData\\TrustBridge\\keys"
  }
}
```

### `PinCache:SurviveRestart`

**Padrão** `false` · **Instalação na frota** decisão do administrador, e um desvio documentado

Se os PINs em cache sobrevivem a um reinício do serviço ou da máquina. **Desligado**, as entradas são
criptografadas com um chaveiro que só existe no processo em execução, então parar o serviço destrói o
meio de lê-las. **Ligado**, o chaveiro é persistido em `KeyRingPath`, protegido com DPAPI no escopo da
máquina, e o texto cifrado vai para `StorePath`, em um arquivo cuja ACL admite apenas SYSTEM e
Administradores. Em qualquer caso, o TTL fica selado dentro do texto cifrado, então um reinício não
consegue zerá-lo e editar o arquivo não consegue estendê-lo.

Ligá-lo é um desvio documentado do gatilho de encerramento do requisito de middleware da ICP-Brasil
(REQUISITO-MW II.27), que o TrustBridge trata como uma diretriz porque fica acima do middleware do
fabricante. Uma máquina com ele ligado avisa isso em `Warning` a cada inicialização.

### O restante do Cache de PIN

| Chave | Padrão | Significado |
|---|---|---|
| `PinCache:Ttl` | 8 h | Quanto tempo uma entrada vive **sem ser usada**. Deslizante: cada uso renova a expiração, então um usuário ativo todo dia nunca é solicitado de novo. Um valor não positivo impede a inicialização. |
| `PinCache:SweepInterval` | 5 min | A frequência com que entradas inativas são removidas da memória. De qualquer forma, nada consegue obter um PIN expirado. |
| `PinCache:StorePath` | `%ProgramData%\TrustBridge\pin-cache.dat` | Onde o texto cifrado é gravado. Nunca é gravado enquanto a sobrevivência estiver desligada. |
| `PinCache:KeyRingPath` | `%ProgramData%\TrustBridge\keys` | Onde fica o chaveiro persistido. Não é usado enquanto a sobrevivência estiver desligada. |

## Logs

A configuração do próprio framework, no mesmo formato da do Servidor. O arquivo fornecido define
`Default` como `Information` e reduz duas categorias do cliente SignalR a `Warning`. Duas linhas que
um administrador deve reconhecer no nível padrão: em qual postura do Cache de PIN a máquina está (a
cada inicialização) e que o mecanismo de tokens falsos para desenvolvimento está ativo (a cada
inicialização, em qualquer máquina com uma seção `FakeTokens`). **Uma seção `FakeTokens` não deve
existir em uma máquina em que alguém assine**: ela faz certificados fabricados serem validados como
`ACTIVE`.

## O Tray App não lê nenhum arquivo de configuração

Não há `appsettings.json` para o Tray App. As opções dele são construídas no código: o nome do pipe e
a versão de protocolo a que ele se conecta, o intervalo de reconexão e a tolerância de expiração da
solicitação são compilados, e o idioma que ele exibe vem da cultura de interface do Windows do usuário
conectado, e não de uma configuração. O que molda o canal entre os dois é a seção `Tray` acima, que é
lida pelo **serviço**.