Approbation des certificats personnalisés

Approbation des certificats personnalisés

La CLI accepte deux paramètres facultatifs sur chaque commande authentifiée qui vous permettent de contrôler la façon dont les certificats TLS d'Orchestrator et d'Identity Server sont validés. Ils sont particulièrement utiles lors de la connexion à UiPath Automation Suite ou à d'autres déploiements Orchestrator dont le certificat d'hôte est signé par une autorité de certification privée (interne, auto-signée) à laquelle le système d'exploitation n'ajoute pas encore d'approbation.

Lorsqu'aucun paramètre n'est fourni, la CLI se comporte exactement comme avant: elle valide le certificat du serveur par rapport au magasin approuvé du système d'exploitation. Les paramètres décrits ci-dessous se cumulent; ils étendent ou contraignent la décision de confiance mais ne l'altérent jamais.

Le paramètre --ca-cert

Ajoute un ou plusieurs fichiers de certificat CA racine approuvés à la décision d'approbation. Ce que le système d'exploitation a déjà approuvé continue de fonctionner; les certificats que vous fournissez ici sont acceptés en outre.

Syntaxe

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

Formats de fichier de certificat pris en charge

Format	Extensions typiques	Remarques
PEM	.pem, .crt, .cer	Format de texte avec -----BEGIN CERTIFICATE----- marqueurs. Un même fichier peut contenir plusieurs certificats concaténés (un « bundle»).
DER	.der, .cer, .crt	Binaire X.509. Certificat unique par fichier.
PKCS#7	.p7b, .p7c	Collection Cert sans clés privées. Le format que Windows Certificate Manager (certmgr.msc) exporte par défaut.

Le format est automatiquement détecté à partir du contenu du fichier, et non de l'extension. Un fichier .cer contenant un bloc PEM et un fichier .cer contenant des octets DER sont tous deux gérés.

Non pris en charge: PFX/PKCS#12 (.pfx, .p12). Ces fichiers comportent des clés privées et sont destinés à l’identité du client, et non à des ancres de confiance. La CLI les rejette avec une erreur explicite.

Plusieurs certificats

Vous pouvez fournir autant de racines que nécessaire. L'indicateur peut être répété, séparé par des virgules, ou les deux formes peuvent être combinées. Les trois commandes ci-dessous sont équivalentes:

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

Dans le troisième formulaire, bundle.pem est un fichier PEM unique contenant les deux certificats concaténés.

---

Le paramètre --pinnedpubkey

Épingle la clé publique du certificat de feuille de serveur à un hachage SHA-256 spécifique. Le format est compatible curl: la chaîne littérale sha256// suivie du SHA-256 encodé en base64 de la valeurSubjectPublicKeyInfo du certificat.

Syntaxe

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

La épingle est vérifiée en plus de la validation du certificat standard, et non à la place. Le certificat doit toujours s'accéder à une racine approuvée et réussir la vérification du nom d'hôte; de plus, sa clé publique doit correspondre au code PIN. Les deux conditions sont requises - correspondant au comportement de la boucle.

Ce que l'épinglage ajoute au-delà de la validation de la chaîne

La validation en chaîne seule indique: « faites confiance à tout certificat signé par ces autorités de certification». La épingle ajoute: «…mais uniquement si sa clé publique correspond à ce hachage exact.» Différentes menaces sont capturées par chaque couche.

Vue	Chaîne uniquement	Chaîne + épingle
Attaque aléatoire sans certificat émis par une autorité de certification	Bloqué	Bloqué
Attaque avec un certificat provenant de n'importe quelle autorité de certification approuvée par votre système (par exemple, une autorité de certification publique inappropriée ou compromise)	Accepté	Bloqué
Votre propre autorité de certification publie un nouveau certificat pour le même nom d’hôte, en réutilisant la même clé (renouvellement légal)	Accepté	Accepté
Votre propre autorité de certification publie un nouveau certificat pour le même nom d’hôte avec une clé différente (saisie de clés ou cible différente)	Accepté	Bloqué

Lorsque l’épinglage correspond au coût opérationnel:

• Protection approfondie sur un serveur approuvé publiquement. Si votre Orchestrator utilise un certificat émis publiquement, la validation en chaîne accepte n'importe quel certificat l'une des 150 CA publiques que votre approbation de système d'exploitation décide d'émettre pour ce nom d'hôte. L'épinglage se réduit au certificat que vous avez l'intention d'accepter.
• Vous ne faites pas entièrement confiance à votre propre équipe CA interne. L'épinglage de la clé publique de la feuille réduit la confiance au certificat que vous avez l'intention d'accepter plutôt que l'autorité de signature de l'autorité de certification.

Lorsque l’épinglage est prioritaire:

• Vous utilisez déjà --ca-cert avec une autorité de certification privée que vous contrôlez entièrement. L'ancre de chaîne est la même racine qui signe la feuille du cluster, et il n'y a pas de deuxième autorité de certification en lecture, de sorte que l'épinglage empêche une classe d'attaque (certificat émis par une autorité de certification malveillante) qui ne peut pas se produire dans votre configuration.

Comment obtenir le code PIN SHA-256

Le code PIN est le hachage SHA-256 de la licenceSubjectPublicKeyInfo du certificat, encodé en base64, préfixé par sha256// Le Service d'algorithme est la partie d'un certificat X.509 qui contient la clé publique avec son identificateur d'algorithme. Il ne s'agit pas du certificat complet et il ne s'agit pas seulement du module brut.

L'épinglage du ServiceSP Configuration plutôt que le certificat complet a une propriété utile: si le serveur réémet son certificat avec la même clé (renouvellement), l'épinglage correspond toujours. La épingle ne doit être modifiée que lorsque le serveur bascule réellement vers une nouvelle paire de clés.

Vous pouvez calculer le code PIN de trois manières, en fonction de l’élément auquel vous avez accès.

From a certificate file (PEM, DER, or .cer)

PowerShell: fonctionne sur Windows prêt à l’emploi, aucun outil supplémentaire n’est nécessaire:

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

Exemple de sortie :

sha256//5FAF491D9F7AC8274B1353B9E2E9317733033EFC22341ABAEA6466037D5123EE=

OpenSSL - fonctionne sur Linux, macOS, Windows avec OpenSSL installé:

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

Ajoutez ensuite sha256// à la chaîne base64 obtenue. Si votre fichier est au format DER (binaire), ajoutez -inform der à la première commande:

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

Directement depuis un serveur en direct

Lorsque vous ne disposez pas du fichier de certificat, mais que le serveur est accessible, récupérez-le via l'établissement de liaison 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 (aucune openssl n'est requise):

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

L'avantage de la récupération à partir du serveur en direct est que vous n'avez pas à trouver et à exporter le fichier de certificat; ce que le serveur présente sur le port 443 est exactement ce que la CLI verra et validera.

À partir d’un certificat déjà présent dans le magasin d’approbation Windows

Si le certificat se trouve dans votre gestionnaire de certificats (certmgr.msc ou certlm.msc), vous pouvez le saisir par empreinte sans l’exporter vers un fichier:

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

Remplacez l'empreinte par celle que vous voyez dans certmgr.msc pour le certificat que vous souhaitez épingler. Remplacez Cert:\CurrentUser\Root, \My ou \CA si le certificat se trouve dans un autre magasin.

Vérification de l'épinglage

Avant d'utiliser une épingle nouvellement calculée dans CI, vérifiez l'intégrité avec curl:

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

• Si la connexion réussit (ou échoue pour une raison sans rapport comme 401), le code PIN est correct.
• Si curl échoue avec SSL: public key does not match pinned public key, recalculez: vous avez très probablement épinglé un certificat différent de celui que le serveur présente réellement.

---

Combinaison des deux paramètres

--ca-cert et --pinnedpubkey composent. Chaque vérification activée doit être réussie indépendamment pour que la connexion réussisse.

--ca-cert Fourni	--pinnedpubkey Fourni	Obligatoire d'accepter
non	non	L’approbation système valide le serveur (comportement actuel)
oui	non	Validations du serveur par rapport à la confiance du système ou à toute racine fournie
non	oui	L’approbation système valide le serveur et la clé publique de la feuille correspond à la code PIN
oui	oui	Le chemin d’approbation valide et la clé publique de la feuille correspond à l’épinglage

La vérification du nom d’hôte est toujours effectuée par rapport au nom alternatif du sujet du certificat de feuille (ou au nom commun si aucun SAN n’est présent), indépendamment des autres indicateurs que vous définissez.

---

Scénarios

Se connecter à UiPath Automation Suite

Les clusters Automation Suite génèrent leur propre certificat UiPath AS Root CA auto-signé lors de l'installation. Pour valider le certificat d'hôte du cluster, exportez cette racine et transmettez-la via --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

Exécuteur CI/CD sans autorisation d’installer de certificats au niveau du système

Les agents CI/CD s'exécutent souvent en tant que comptes de service non administrateurs qui ne peuvent pas modifier le magasin d'approbation du système d'exploitation. --ca-cert étend la confiance à l’invocation de CLI actuelle uniquement.

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"

L’agent n’a besoin que d’un accès en lecture au fichier de certificat; aucun privilège élevé, aucune modification de l’état de la machine.

Plusieurs cibles Orchestrator dans un même pipeline

Lorsqu'un pipeline se déploie vers plusieurs instances d'Orchestrator signées par des certificats CA internes différents, indiquez la racine du cluster en une seule fois. Le magasin d'approbation système s'applique toujours, de sorte que les Orchestrator publics dans le même pipeline continuent de fonctionner sans configuration supplémentaire.

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"

Protection approfondie sur un serveur approuvé publiquement

Même lorsque le serveur est signé par une autorité de certification publique approuvée par le système d'exploitation, vous pouvez épingler la clé publique pour détecter la compromission de n'importe quelle autorité de certification dans le magasin d'approbation du système. Si un certificat mal émis est présenté pour le même nom d'hôte, l'épinglage le rejette même si la validation de la chaîne a réussi.

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

Épingler derrière une autorité de certification privée

Lorsque le serveur utilise une autorité de certification privée, les deux indicateurs sont requis. La épingle seule ne contourne pas la validation de la chaîne.

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

Épingler la durée de vie dans la rotation des certificats

Le code PIN suit la clé publique, et non le certificat. Lorsque le certificat du serveur est renouvelé, mais que sa clé privée est réutilisée, le SHA-256 deSubjectPublicKeyInfo reste le même et votre code PIN continue de fonctionner. Lorsque le serveur génère une nouvelle paire de clés, la épingle est interrompue et vous devez la recalculer et la mettre à jour.

Pour Automation Suite en particulier, le comportement de rotation des certificats dépend de la configuration cert-manager du cluster. Testez une fois après la première rotation: si la épingle recalculée correspond à l'ancienne, vous avez confirmé que le cluster réutilise les clés et que la épingle est solide; si elle diffère, attendez-vous à actualiser la épingle à chaque rotation.

---

Résolution des problèmes

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

Le chemin relatif a été résolu par rapport au répertoire de travail actuel et aucun fichier n’existe à ce chemin absolu. Transmettez un chemin absolu ou assurez-vous que la CLI s'exécute à partir du répertoire attendu.

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

Le fichier PEM que vous avez fourni contient un bloc de clé privée en plus du certificat. Supprimez la clé (elle n'a aucun rôle d'ancre de confiance) et réessayez.

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

Le fichier est très probablement un PFX/PKCS#12. Réexportez-la sans la clé privée ou convertissez-la en PEM avec 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 chaîne après sha256// n'a pas été codée en base64 sur exactement 32 octets. Recalculez l'épinglage à l'aide de l'une des formules ci-dessus.

Connection still fails with --pinnedpubkey set against an internal server

La épingle seule ne contourne pas la validation de la chaîne. Ajoutez --ca-cert <root> pour que la chaîne dispose d'une ancre de confiance.