Confiança em certificados personalizados

Confiança em certificados personalizados

A CLI aceita dois parâmetros opcionais em cada comando autenticado que permitem que você controle como os certificados TLS do Orchestrator e do Identity Server são validados. Elas são mais úteis ao conectar-se ao UiPath Automation Suite ou outras implantações do Orchestrator cujo certificado de host é assinado por uma Autoridade de Certificação privada (interna e autoassinada) na qual o sistema operacional já não confia.

Quando nenhum parâmetro é fornecido, a CLI se comporta exatamente como antes - valida o certificado do servidor contra o armazenamento de confiança do sistema operacional. Os parâmetros descritos abaixo são cumulativos; eles estendem ou restringem a decisão de confiança, mas nunca a enriquecem.

parâmetro --ca-cert

Adiciona um ou mais arquivos de certificado de CA raiz confiáveis à decisão de confiança. O que quer que o sistema operacional já confie continua a funcionar; os certificados que você fornece aqui são aceitos além disso.

Sintaxe

--ca-cert <path>
--ca-cert <path1>,<path2>,...
--ca-cert <path1> --ca-cert <path2>

Formatos de arquivo de certificado compatíveis

Format	Extensões típicas	Observações
PEM	.pem, .crt, .cer	Formato de texto com -----BEGIN CERTIFICATE----- . Um único arquivo pode conter vários certificados concatenados (um "pacote").
DER	.der, .cer, .crt	Binário X.509. Certificado único por arquivo.
PKCS#7	.p7b, .p7c	Coleção de certificados sem chaves privadas. O formato que o Gerenciador de Certificados do Windows (certmgr.msc) exporta por padrão.

O formato é detectado automaticamente a partir do conteúdo do arquivo, não da extensão - um arquivo .cer contendo um bloco PEM e um arquivo .cer contendo bytes DER são ambos tratados.

Não compatível: PFX/PKCS#12 (.pfx, .p12). Esses arquivos carregam chaves privadas e são destinados à identidade do cliente, não como âncoras de confiança. A CLI os rejeita com um erro explícito.

Vários certificados

Você pode fornecer quantas raiz forem necessárias. O sinalizador pode ser repetido, separado por vírgula ou ambas as formas podem ser combinadas. Os três comandos abaixo são equivalentes:

--ca-cert "C:\certs\as-root.pem" --ca-cert "C:\certs\corp-root.pem"
--ca-cert "C:\certs\as-root.pem,C:\certs\corp-root.pem"
--ca-cert "C:\certs\bundle.pem"

Na terceira forma, é um bundle.pem arquivo PEM contendo ambos os certificados concatenados.

---

parâmetro --pinnedpubkey

Fixa a chave pública do certificado leaf do servidor a um hash SHA-256 específico. O formato é compatível com curl: a string literal sha256// seguida pelo SHA-256 codificado em base64 do SubjectPublicKeyInfo do certificado.

Sintaxe

--pinnedpubkey "sha256//<base64 hash>"

O pino é verificado além da validação de certificado padrão, não em vez dela. O certificado ainda deve encadear-se a uma raiz confiável e passar na verificação do nome do host; além disso, sua chave pública deve corresponder ao pino. Ambas as condições são necessárias - correspondendo ao comportamento da curl.

O que a marcação adiciona além da validação em cadeia

A validação em cadeia isoladamente diz: "confie em qualquer certificado assinado por essas CAs". O pino adiciona: "…mas apenas se sua chave pública corresponder a esse hash exato." Diferentes ameaças são capturadas por cada camada.

Ameaça	Cadeia isolada	Cadeia + pino
Invocador aleatório sem certificado emitido por CA	Bloqueado	Bloqueado
Invocador com um certificado de qualquer CA que seu sistema já confie (por exemplo, CA pública emitida incorretamente ou comprometida)	Aceito	Bloqueado
Sua própria CA emite um novo certificado para o mesmo nome do host, reutilizando a mesma chave (renovação válida)	Aceito	Aceito
Sua própria CA emite um novo certificado para o mesmo nome do host com uma chave diferente (reativação ou ataque)	Aceito	Bloqueado

Quando a anexação vale o custo operacional:

• Proteção de profundidade em um servidor publicamente confiável. Se seu Orchestrator usar um certificado emitido publicamente, a validação em cadeia aceita qualquer certificado que qualquer uma das cerca de 150 CAs públicas que seu sistema operacional confia emitir para esse nome de host. O pino reduz para aquele certificado que você pretende aceitar.
• Você não confia totalmente em sua própria equipe de CA interna. Fixar a chave pública da folha restringe a confiança ao único certificado que você pretende aceitar, em vez de toda a autoridade de assinatura da CA.

Quando fixar é um excesso:

• Você já está usando --ca-cert em uma CA privada que você controla totalmente. A âncora de cadeia é a mesma raiz que assina a folha do cluster e não há uma segunda CA em ação, portanto, a fixar impede uma classe de ataque (cert emitido por CA desonesto) que não pode acontecer em sua configuração.

Como obter o PIN SHA-256

O PIN é o hash SHA-256 do SubjectPublicKeyInfo (SPKI) do certificado, codificado em base64, prefixado com sha256//. O SPKI é a parte de um certificado X.509 que contém a chave pública junto com seu identificador de algoritmo - não é o certificado completo e não é apenas o módulo bruto.

Fixar o SPKI em vez do certificado completo tem uma propriedade útil: se o servidor reemitir seu certificado com a mesma chave (uma renovação), a fixar ainda corresponderá. O pino só precisa ser alterado quando o servidor realmente gira para um novo par de chaves.

Você pode calcular o PIN de três maneiras, dependendo do que você tem acesso.

A partir de um arquivo de certificado (pem, DER ou .cer)

PowerShell - funciona no Windows pronto para uso, sem necessidade de ferramentas extras:

$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new(
    'C:\certs\orchestrator-leaf.cer')
$spki = $cert.PublicKey.ExportSubjectPublicKeyInfo()
$hash = [System.Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

Amostra de saída:

sha256//5FAF491D9F7AC8274B1353B9E2E9317733033EFC22341ABAEA6466037D5123EE=

OpenSSL - funciona no Linux, macOS, Windows com OpenSSL instalado:

openssl x509 -in cert.pem -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

Em seguida, anexe sha256// à string base64 resultante. Se seu arquivo estiver no formato DER (binário), adicione -inform der ao primeiro comando:

openssl x509 -in cert.der -inform der -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

Direitamente de um servidor em tempo real

Quando você não tiver o arquivo de certificado, mas o servidor estiver acessível, recupere-o por meio do próprio handshake de TLS.

OpenSSL:

HOST=orchestrator.your-cluster.internal
openssl s_client -servername $HOST -connect $HOST:443 < /dev/null 2>/dev/null |
  openssl x509 -pubkey -noout |
  openssl pkey -pubin -outform der |
  openssl dgst -sha256 -binary |
  openssl base64

PowerShell (não openssl é necessário):

$h = 'orchestrator.your-cluster.internal'
$tcp = [Net.Sockets.TcpClient]::new($h, 443)
$cb  = [Net.Security.RemoteCertificateValidationCallback]{ param($s,$c,$ch,$e) $script:cert=$c; $true }
$ssl = [Net.Security.SslStream]::new($tcp.GetStream(), $false, $cb)
$ssl.AuthenticateAsClient($h); $ssl.Close(); $tcp.Close()
$cert2 = [Security.Cryptography.X509Certificates.X509Certificate2]::new($script:cert)
$spki  = $cert2.PublicKey.ExportSubjectPublicKeyInfo()
$hash  = [Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

A vantagem de buscar no servidor ativo é que você não precisa localizar e exportar o arquivo do certificado - o que o servidor apresentar na porta 443 é exatamente o que a CLI verá e validará.

De um certificado que já está no armazenamento de confiança do Windows

Se o certificado estiver em seu Gerenciador de certificados (certmgr.msc ou certlm.msc), você poderá obtê-lo por impressão digital sem exportá-lo para um arquivo:

$cert = Get-ChildItem -Path Cert:\LocalMachine\Root |
    Where-Object { $_.Thumbprint -eq 'AD2C67543E1A2A347B13E4471FA945EC77566FC1' } |
    Select-Object -First 1
$spki = $cert.PublicKey.ExportSubjectPublicKeyInfo()
$hash = [System.Security.Cryptography.SHA256]::HashData([byte[]]$spki)
"sha256//" + [Convert]::ToBase64String($hash)

Substitua a impressão digital pela que você vê em certmgr.msc para o certificado que deseja fixar. Substitua Cert:\CurrentUser\Root, \My ou \CA se o certificado estiver em um armazenamento diferente.

Verificando o PIN

Antes de usar um pino recém-calculado no CI, verifique a sanidade com curl:

curl -I --pinnedpubkey 'sha256//<base64>=' https://orchestrator.your-cluster.internal/

• Se a conexão for bem-sucedida (ou falhar por um motivo não relacionado, como 401), o pino está correto.
• Se curl falhar com SSL: public key does not match pinned public key, recalcule - você provavelmente fixou um certificado diferente daquele que o servidor realmente apresenta.

---

Combinando os dois parâmetros

--ca-cert e --pinnedpubkey compõem. Cada verificação habilitada deve ser aprovada de forma independente para que a conexão seja bem-sucedida.

--ca-cert Fornecido	--pinnedpubkey Fornecido	Necessário aceitar
não	não	A confiança do sistema valida o servidor (comportamento atual)
sim	não	O servidor valida em relação à confiança do sistema ou a qualquer raiz fornecida
não	sim	A confiança do sistema valida o servidor e a chave pública da folha corresponde ao PIN
sim	sim	O caminho de confiança valida e a chave pública da folha corresponde ao PIN

A verificação do nome do host é sempre realizada em relação ao Nome Alternativo do Assunto do certificado de folha (ou Nome Comum se nenhum SAN estiver presente), independentemente de quais outros sinalizadores você definir.

---

Scenarios

Conexão com o UiPath Automation Suite

Os clusters do Automation Suite geram seu próprio certificado UiPath AS Root CA autoassinado durante a instalação. Para validar o certificado do host do cluster, exporte essa raiz e passe-a por meio de --ca-cert.

uipcli solution upload-package "C:\Work\MySolution.1.0.0.zip" `
  -U "https://orchestrator.your-cluster.internal/" `
  -T "DefaultTenant" `
  -A "Default" `
  -I "<your application id>" `
  -S "<your application secret>" `
  --ca-cert "C:\certs\uipath-as-root.crt" `
  --traceLevel Information

Executor de CI/CD sem permissão para instalar certificados em todo o sistema

Os agentes de CI/CD geralmente são executados como contas de serviço sem administrador que não podem modificar o armazenamento de confiança do sistema operacional. --ca-cert delimita a confiança apenas para a invocação da CLI atual.

uipcli package deploy "./output/MyPackage.1.0.0.nupkg" "https://orchestrator.internal/" "DefaultTenant" `
  -A "Default" -I "$env:APP_ID" -S "$env:APP_SECRET" `
  -o "Production" `
  --ca-cert "$env:CI_WORKSPACE/certs/internal-root.pem"

O agente só precisa de acesso de leitura ao arquivo de certificado - sem privilégios elevados, sem alterações no estado da máquina.

Vários destinos do Orchestrator em um único pipeline

Quando um pipeline é implantado em várias instâncias do Orchestrator assinadas por diferentes CAs internas, forneça a raiz de cada cluster de uma só vez. O armazenamento de confiança do sistema ainda se aplica, portanto, os Orchestrators públicos no mesmo pipeline continuam funcionando sem configurações adicionais.

uipcli package deploy "./pkg.nupkg" "https://orch-1.internal/" "Tenant1" `
  -A "Org" -I "<id>" -S "<secret>" -o "Folder" `
  --ca-cert "./certs/orch-1.pem,./certs/orch-2.pem"

Proteção detalhada em um servidor publicamente confiável

Mesmo quando o servidor é assinado por uma CA pública na qual o sistema operacional já confia, você pode fixar a chave pública para detectar um compromisso de qualquer CA no armazenamento de confiança do sistema. Se um certificado emitido incorretamente for apresentado para o mesmo nome de host, o PIN o rejeitará mesmo que a validação em cadeia tenha sido aprovada.

uipcli job run MyProcess "https://cloud.uipath.com/" "Tenant" `
  -A "OrgName" -I "<id>" -S "<secret>" -o "Folder" `
  --pinnedpubkey "sha256//<base64 hash>"

Fixação atrás de uma CA privada

Quando o servidor usa uma CA privada, ambos os sinalizadores são necessários. O pino sozinho não ignora a validação da cadeia.

uipcli solution upload-package "MyPackage.1.0.0.zip" `
  -U "https://orchestrator.internal/" -T "Tenant" `
  -A "Org" -I "<id>" -S "<secret>" `
  --ca-cert "./certs/internal-root.pem" `
  --pinnedpubkey "sha256//<base64 hash>"

Fixe a duração em toda a rotação do certificado

O pino rastreia a chave pública, não o certificado. Quando o certificado do servidor é renovado, mas sua chave privada é reutilizada, o SHA-256 de SubjectPublicKeyInfo permanece o mesmo e seu PIN continua funcionando. Quando o servidor gera um novo par de chaves, ele é interrompido e você precisará recalculá-lo e atualizá-lo.

Para o Automation Suite especificamente, o comportamento da rotação de certificados depende da configuração cert-manager do cluster. Teste uma vez após a primeira rotação: se o pino recalculado corresponder ao antigo, você confirma que o cluster reutiliza chaves e que o pino é estável; se for diferente, espere atualizar o pino a cada rotação.

---

Solução de problemas

--ca-cert file not found: ./certs/root.pem (resolved to /actual/cwd/certs/root.pem)

O caminho relativo resolvido em relação ao diretório de trabalho atual e nenhum arquivo existe nesse caminho absoluto. Transmita um caminho absoluto ou certifique-se de que a CLI seja executada a partir do diretório esperado.

--ca-cert expects certificates only; '<path>' contains a private key block.

O arquivo PEM que você forneceu contém um bloco de chaves privadas além do certificado. Remova a chave (ela não tem função como uma âncora de confiança) e tente novamente.

Could not parse '<path>' as a certificate (PEM/DER/PKCS#7 supported, PFX/PKCS#12 is not).

Provavelmente o arquivo é um PFX/PKCS#12. Exporte-a novamente sem a chave privada ou converta-a para PEM com openssl pkcs12 -in cert.pfx -nokeys -out cert.pem.

--pinnedpubkey must be a SHA-256 hash (32 bytes); got <N> bytes after base64-decoding.

A string após sha256// não decodizou em base64 exatamente 32 bytes. Recalcule o pino usando uma das fórmulas acima.

A conexão ainda falha com --pinnedpubkey definido em um servidor interno

O pino sozinho não ignora a validação da cadeia. Adicione --ca-cert <root> para que a cadeia tenha uma âncora de confiança.