Confiar en certificados personalizados

Confiar en certificados personalizados

La CLI acepta dos parámetros opcionales en cada comando autenticado que te permiten controlar cómo se validan los certificados TLS de Orchestrator e Identity Server. Son más útiles cuando se conectan a UiPath Automation Suite u otras implementaciones de Orchestrator cuyo certificado de host está firmado por una autoridad de certificación privada (interna, autofirmada) en la que el sistema operativo no confía.

Cuando no se proporciona ningún parámetro, la CLI se comporta exactamente como antes: valida el certificado del servidor con el almacén de confianza del sistema operativo. Los parámetros descritos a continuación son aditivos; amplían o restringen la decisión de confianza, pero nunca la debilitan.

El parámetro --ca-cert

Añade uno o más archivos de certificado de CA raíz de confianza a la decisión de confianza. Cualquier cosa en la que el sistema operativo ya confíe sigue funcionando; los certificados que proporciones aquí se aceptan además de eso.

Sintaxis

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

Formatos de archivo de certificado compatibles

Formato	Extensiones típicas	Notas
PEM	.pem, .crt, .cer	Formato de texto con marcadores -----BEGIN CERTIFICATE----- . Un único archivo puede contener varios certificados concatenados (un "paquete").
Der	.der, .cer, .crt	Binario X.509. Certificado único por archivo.
PKCS#7	.p7b, .p7c	Colección de certificados sin claves privadas. El formato que exporta el Gestor de certificados de Windows (certmgr.msc) de forma predeterminada.

El formato se detecta automáticamente a partir del contenido del archivo, no de la extensión: se gestionan tanto un archivo .cer que contiene un bloque PEM como un archivo .cer que contiene bytes DER.

No compatible: PFX/PKCS#12 (.pfx, .p12). Estos archivos contienen claves privadas y están destinados a la identidad del cliente, no como anclajes de confianza. La CLI los rechaza con un error explícito.

Varios certificados

Puedes proporcionar tantas raíces como necesites. El marcador puede repetirse, estar separado por comas o combinarse ambas formas. Los tres comandos siguientes son 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"

En el tercer formulario, bundle.pem es un único archivo PEM que contiene ambos certificados concatenados.

---

El parámetro --pinnedpubkey

Ancla la clave pública del certificado de hoja del servidor a un hash SHA-256 específico. El formato es compatible con curl: la cadena literal sha256// seguida del SHA-256 codificado en base64 de la información de clave pública del asunto del certificado.

Sintaxis

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

El pin se comprueba además de la validación del certificado estándar, no en su lugar. El certificado aún debe encadenarse a una raíz de confianza y pasar la comprobación del nombre de host; además, su clave pública debe coincidir con el pin. Se requieren ambas condiciones: que coincidan con el comportamiento de curl.

Qué añade la fijación más allá de la validación de la cadena

Solo la validación de la cadena dice: "confiar en cualquier certificado firmado por estas AC". El pin añade: "... pero solo si su clave pública coincide con este hash exacto". Cada capa detecta diferentes amenazas.

Amenaza	Cadena sola	Cadena + alfiler
Atacante aleatorio sin certificado emitido por una CA	Bloqueado	Bloqueado
Atacante con un certificado de cualquier CA en la que su sistema ya confíe (por ejemplo, una CA pública mal emitida o comprometida)	Aceptado	Bloqueado
Su propia CA emite un nuevo certificado para el mismo nombre de host, reutilizando la misma clave (renovación legítima)	Aceptado	Aceptado
Su propia CA emite un nuevo certificado para el mismo nombre de host con una clave diferente (reintroducción o ataque)	Aceptado	Bloqueado

Cuándo fijar vale la pena el coste operativo:

• Defensa en profundidad en un servidor de confianza pública. Si tu Orchestrator utiliza un certificado emitido públicamente, la validación de la cadena acepta cualquier certificado que cualquiera de las ~150 CA públicas en las que confía tu sistema operativo decida emitir para ese nombre de host. El pin lo reduce al único certificado que pretendes aceptar.
• No confía plenamente en su propio equipo interno de CA. Anclar la clave pública de la hoja reduce la confianza al único certificado que pretendes aceptar en lugar de a la autoridad de firma completa de la CA.

Cuando fijar es excesivo:

• Ya está utilizando --ca-cert contra una CA privada que controla por completo. El anclaje de la cadena es la misma raíz que firma la hoja del clúster, y no hay una segunda CA en juego, por lo que la fijación evita una clase de ataque (certificado emitido por una CA no autorizada) que no puede ocurrir en tu configuración.

Cómo obtener el pin SHA-256

El pin es el hash SHA-256 delSubjectPublicKeyInfo (SPKI) del certificado, codificado en base64, con el prefijo sha256//. El SPKI es la parte de un certificado X.509 que contiene la clave pública junto con su identificador de algoritmo; no es el certificado completo, y no es solo el módulo sin procesar.

Anclar el SPKI en lugar del certificado completo tiene una propiedad útil: si el servidor vuelve a emitir su certificado con la misma clave (una renovación), el pin sigue coincidiendo. El pin solo tiene que cambiar cuando el servidor realmente rota a un nuevo par de claves.

Puedes calcular el pin de tres maneras, dependiendo de a qué tengas acceso.

Desde un archivo de certificado (PEM, DER o .cer)

PowerShell: funciona en Windows desde el primer momento, no se necesitan herramientas adicionales:

$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)

Salida de ejemplo:

sha256//5FAF491D9F7AC8274B1353B9E2E9317733033EFC22341ABAEA6466037D5123EE=

OpenSSL: funciona en Linux, macOS, Windows con OpenSSL instalado:

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

A continuación, antepone sha256// a la cadena base64 resultante. Si tu archivo está en formato DER (binario), añade -inform der al primer comando:

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

Directamente desde un servidor activo

Cuando no tengas el archivo de certificado pero se pueda acceder al servidor, recupéralo a través del propio protocolo de enlace 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 (no se requiere openssl):

$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)

La ventaja de obtener desde el servidor en vivo es que no tienes que buscar y exportar el archivo de certificado: lo que sea que el servidor presente en el puerto 443 es exactamente lo que la CLI verá y validará.

Desde un certificado que ya está en el almacén de confianza de Windows

Si el certificado está en tu Gestor de certificados (certmgr.msc o certlm.msc), puedes obtenerlo mediante la huella digital sin exportarlo a un archivo:

$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)

Sustituye la huella digital por la que ves en certmgr.msc para el certificado que quieres anclar. Sustituye Cert:\CurrentUser\Root, \My o \CA si el certificado está en un almacén diferente.

Verificar el pin

Antes de utilizar un pin recién calculado en CI, compruébalo con curl:

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

• Si la conexión se realiza correctamente (o falla por un motivo no relacionado como 401), el pin es correcto.
• Si curl falla con SSL: public key does not match pinned public key, vuelve a calcular: lo más probable es que hayas fijado un certificado diferente al que realmente presenta el servidor.

---

Combinar los dos parámetros

--ca-cert y --pinnedpubkey redactan. Cada comprobación habilitada debe pasar de forma independiente para que la conexión se realice correctamente.

--ca-cert proporcionado	--pinnedpubkey proporcionado	Obligatorio para aceptar
No	No	La confianza del sistema valida el servidor (comportamiento actual)
Sí	No	El servidor valida contra la confianza del sistema o cualquier raíz proporcionada
No	Sí	La confianza del sistema valida el servidor y la clave pública de la hoja coincide con el pin
Sí	Sí	La ruta de confianza valida y la clave pública de la hoja coincide con el pin

La comprobación del nombre de host siempre se realiza con el nombre alternativo del asunto del certificado de hoja (o el nombre común si no hay SAN), independientemente de los otros marcadores que establezcas.

---

Scenarios

Conexión a UiPath Automation Suite

Los clústeres de Automation Suite generan su propio certificado UiPath AS Root CA autofirmado durante la instalación. Para validar el certificado de host del clúster, exporta esa raíz y pásala a través 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

Ejecutor CI/CD sin permiso para instalar certificados en todo el sistema

Los agentes CI/CD a menudo se ejecutan como cuentas de servicio que no son de administrador y que no pueden modificar el almacén de confianza del sistema operativo. --ca-cert limita el ámbito de confianza solo a la invocación CLI actual.

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"

El agente solo necesita acceso de lectura al archivo del certificado: sin privilegios elevados, sin cambios en el estado de la máquina.

Varios destinos de Orchestrator en un solo proceso

Cuando un proceso se implementa en varias instancias de Orchestrator firmadas por diferentes AC internas, proporciona la raíz de cada clúster de una sola vez. El almacén de confianza del sistema sigue aplicándose, por lo que los Orchestrators públicos en el mismo proceso siguen funcionando sin necesidad de configuración adicional.

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"

Defensa en profundidad en un servidor de confianza pública

Incluso cuando el servidor está firmado por una CA pública en la que el sistema operativo ya confía, puedes anclar la clave pública para detectar un compromiso de cualquier CA en el almacén de confianza del sistema. Si se presenta un certificado mal emitido para el mismo nombre de host, el pin lo rechaza aunque se haya pasado la validación de la cadena.

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

Anclar detrás de una CA privada

Cuando el servidor utiliza una CA privada, se requieren ambos marcadores. El pin por sí solo no omite la validación de la cadena.

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>"

Durabilidad de los pines en la rotación de certificados

El pin realiza un seguimiento de la clave pública, no del certificado. Cuando se renueva el certificado del servidor pero se reutiliza su clave privada, el SHA-256 de laSubjectPublicKeyInfo permanece igual y tu pin sigue funcionando. Cuando el servidor genera un nuevo par de claves, el pin se rompe y tendrás que volver a calcularlo y actualizarlo.

Para Automation Suite específicamente, el comportamiento de rotación de certificados depende de la cert-manager configuración del clúster. Prueba una vez después de la primera rotación: si el pin recalculado coincide con el anterior, has confirmado que el clúster reutiliza las claves y el pin es duradero; si difiere, espera actualizar el pin en cada rotación.

---

Solución de problemas

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

La ruta relativa se resolvió en el directorio de trabajo actual y no existe ningún archivo en esa ruta absoluta. Pasa una ruta absoluta o asegúrate de que la CLI se ejecuta desde el directorio esperado.

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

El archivo PEM que has proporcionado contiene un bloque de clave privada además del certificado. Elimine la clave (no tiene ningún rol como anclaje de confianza) y vuelva a intentarlo.

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

Lo más probable es que el archivo sea un PFX/PKCS#12. Vuelve a exportarlo sin la clave privada o conviértelo a PEM openssl pkcs12 -in cert.pfx -nokeys -out cert.pem.

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

La cadena después de sha256// no se decodificaba en base64 exactamente a 32 bytes. Vuelve a calcular el pin utilizando una de las recetas anteriores.

La conexión sigue fallando con --pinnedpubkey establecido en un servidor interno

El pin por sí solo no omite la validación de la cadena. Añade --ca-cert <root> para que la cadena tenga un anclaje de confianza.