Vertrauenswürdige benutzerdefinierte Zertifikate

Vertrauenswürdige benutzerdefinierte Zertifikate

Die CLI akzeptiert zwei optionale Parameter für jeden authentifizierten Befehl, mit dem Sie steuern können, wie die Orchestrator- und Identity Server-TLS-Zertifikate validiert werden. Sie sind am nützlichsten, wenn Sie eine Verbindung mit der UiPath Automation Suite oder anderen Orchestrator-Bereitstellungen herstellen, deren Hostzertifikat von einer privaten (internen, selbstsignierten) Zertifizierungsstelle signiert ist, der das Betriebssystem noch nicht vertraut.

Wenn keiner der Parameter angegeben ist, verhält sich die CLI genau wie zuvor – sie überprüft das Serverzertifikat anhand des Vertrauensspeichers des Betriebssystems. Die unten beschriebenen Parameter sind zusätzlich; Sie erweitern oder schränken die Vertrauensentscheidung ein, gefährdet sie aber nie.

Der --ca-cert -Parameter

Fügt der Vertrauensentscheidung eine oder mehrere Dateien mit Stammzertifikaten von Zertifizierungsstellen hinzu. Was das Betriebssystem bereits vertraut, funktioniert weiterhin; Die hier bereitgestellten Zertifikate werden zudem akzeptiert.

Syntax

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

Unterstützte Dateiformate für Zertifikate

Format	Typische Erweiterungen	Hinweise
PEM	.pem, .crt, .cer	Textformat mit -----BEGIN CERTIFICATE----- Markern. Eine einzelne Datei kann mehrere verkettete Zertifikate enthalten (ein „Paket“).
DER	.der, .cer, .crt	Binär X.509. Einzelzertifikat pro Datei.
PKCS#7	.p7b, .p7c	Zertifikatsammlung ohne private Schlüssel. Das Format „Windows Certificate Manager“ (certmgr.msc) wird standardmäßig exportiert.

Das Format wird automatisch aus dem Dateiinhalt erkannt, nicht aus der Erweiterung – eine .cer -Datei mit einem PEM-Block und eine .cer -Datei mit DER-Bytes werden beide verarbeitet.

Nicht unterstützt: PFX/PKCS#12 (.pfx, .p12). Diese Dateien enthalten private Schlüssel und sind für die Clientidentität vorgesehen, nicht als Vertrauensanker. Die CLI weist sie mit einem expliziten Fehler zurück.

Mehrere Zertifikate

Sie können so viele Stammverzeichnisse angeben, wie Sie benötigen. Das Flag kann wiederholt oder durch Kommas getrennt werden oder beide Formulare können kombiniert werden. Die folgenden drei Befehle sind gleichwertig:

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

Im dritten Formular ist bundle.pem eine einzelne PEM-Datei, die beide Zertifikate verkettet enthält.

---

Der --pinnedpubkey -Parameter

Heftet den öffentlichen Schlüssel des Serverblattzertifikats an einen bestimmten SHA-256-Hash an. Das Format ist curl-kompatibel: die Literalzeichenfolge sha256// gefolgt vom base64-codierten SHA-256 der SubjectPublicKeyInfo des Zertifikats.

Syntax

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

Der Pins wird zusätzlich zur Standardzertifikatvalidierung geprüft, nicht anstelle dieser. Das Zertifikat muss trotzdem mit einem vertrauenswürdigen Stamm verkettet sein und die Hostnamenprüfung bestehen; außerdem muss der öffentliche Schlüssel mit dem Pins übereinstimmen. Beide Bedingungen sind erforderlich – sie entsprechen dem Verhalten von curl.

Was das Anheften über die Kettenvalidierung hinaus hinzufügt

Allein die Kettenvalidierung besagt: „Vertraue jedem Zertifikat, das von diesen Zertifizierungsstellen signiert wurde.“ Der Pin fügt Folgendes hinzu: „…aber nur, wenn der öffentliche Schlüssel genau mit diesem Hash übereinstimmt.“ Von jeder Ebene werden unterschiedliche Bedrohungen erfasst.

Bedrohung	Nur Kette	Kette + Pins
Zufälliger Angreifer ohne von der Zertifizierungsstelle ausgestelltes Zertifikat	Blockiert	Blockiert
Angreifer mit einem Zertifikat einer Zertifizierungsstelle, der Ihr System bereits vertraut (z. B. eine falsch ausgestellte oder kompromittierte öffentliche Zertifizierungsstelle)	Akzeptiert	Blockiert
Ihre eigene Zertifizierungsstelle stellt ein neues Zertifikat für denselben Hostnamen aus und verwendet denselben Schlüssel wieder (legacy Erneuerung).	Akzeptiert	Akzeptiert
Ihre eigene Zertifizierungsstelle stellt ein neues Zertifikat für denselben Hostnamen mit einem anderen Schlüssel aus (erneuter Schlüssel oder Angriff)	Akzeptiert	Blockiert

Wenn das Anheften die Betriebskosten wert ist:

• vertiefte Sicherheit auf einem öffentlich vertrauenswürdigen Server. Wenn Ihr Orchestrator ein öffentlich ausgestelltes Zertifikat verwendet, akzeptiert die Kettenvalidierung jedes Zertifikat, das eine der ~150 öffentlichen Zertifizierungsstellen, denen Ihr Betriebssystem vertraut, für diesen Hostnamen ausstellt. Die Pins grenzen dies auf das Zertifikat ein, das Sie akzeptieren möchten.
• Sie vertrauen Ihrem eigenen internen Zertifizierungsstellenteam nicht voll. Das Anheften des öffentlichen Schlüssels des Blatts beschränkt die Vertrauensstellung auf ein Zertifikat, das Sie akzeptieren möchten, und nicht auf die Signaturautorität der gesamten Zertifizierungsstelle.

Wenn das Anheften übertrieben ist:

• Sie verwenden --ca-cert bereits für eine private Zertifizierungsstelle, die Sie vollständig steuern. Der Kettenanker ist dieselbe Stammzertifikat, das das Blatt des Clusters signiert, und es ist keine zweite Zertifizierungsstelle im Spiel, sodass das Anheften eine Angriffsklasse (ungesbasiertes Zertifikat), die in Ihrem Setup nicht auftreten kann, verhindert.

So erhalten Sie den SHA-256-Connector

Der Pin ist der SHA-256-Hash der SubjectPublicKeyInfo (SPKI) des Zertifikats, base64-codiert und mit dem Präfix sha256//. Das SPKI ist der Teil eines X.509-Zertifikats, das den öffentlichen Schlüssel zusammen mit seinem Algorithmusbezeichner enthält – es ist nicht das vollständige Zertifikat und nicht nur das Rohmodul.

Das Anheften des SPKI und nicht des vollständigen Zertifikats hat eine nützliche Eigenschaft: Wenn der Server sein Zertifikat mit demselben Schlüssel erneut ausstellt (eine Erneuerung), stimmt die Pins weiterhin überein. Der Pin muss sich nur ändern, wenn der Server tatsächlich zu einem neuen Schlüsselpaar rotiert wird.

Sie können den Pins auf drei Arten berechnen, je nachdem, worauf Sie Zugriff haben.

Aus einer Zertifikatdatei (PEM, DER oder .cer)

PowerShell – funktioniert sofort unter Windows, keine zusätzlichen Tools erforderlich:

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

Beispielausgabe:

sha256//5FAF491D9F7AC8274B1353B9E2E9317733033EFC22341ABAEA6466037D5123EE=

OpenSSL – funktioniert unter Linux, macOS, Windows mit installiertem OpenSSL:

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

Stellen Sie dann sha256// an die resultierende Base64-Zeichenfolge voran. Wenn Ihre Datei im DER-Format (binär) vorliegt, fügen Sie -inform der zum ersten Befehl hinzu:

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

Direkt von einem Live-Server

Wenn Sie die Zertifikatdatei nicht haben, der Server aber erreichbar ist, rufen Sie sie über den TLS-Handshake selbst ab.

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 (kein OpenSSL erforderlich):

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

Der Vorteil des Abrufens vom Live-Server besteht darin, dass Sie die Zertifikatdatei nicht finden und exportieren müssen – alles, was der Server auf Port 443 präsentiert, ist genau das, was die CLI sieht und gegen das sie validiert.

Aus einem Zertifikat, das sich bereits im Windows-Vertrauensspeicher befindet

Wenn sich das Zertifikat in Ihrem Zertifikatsmanager (certmgr.msc oder certlm.msc) befindet, können Sie es mit dem Fingerabdruck abrufen, ohne es in eine Datei zu exportieren:

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

Ersetzen Sie den Fingerabdruck durch den, den Sie in certmgr.msc für das Zertifikat sehen, das Sie anheften möchten. Ersetzen Sie Cert:\CurrentUser\Root, \My oder \CA wenn sich das Zertifikat in einem anderen Speicher befindet.

Überprüfen des Pins

Bevor Sie eine neu berechnete Pins in CI verwenden, überprüfen Sie sie mit curl auf Integrität:

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

• Wenn die Verbindung erfolgreich ist (oder aus einem anderen Grund wie 401 fehlschlägt), ist der Pin korrekt.
• Wenn curl mit SSL: public key does not match pinned public key fehlschlägt, berechnen Sie neu – Sie haben höchstwahrscheinlich ein anderes Zertifikat angeheftet als das, das der Server tatsächlich präsentiert.

---

Kombinieren der beiden Parameter

--ca-cert und --pinnedpubkey bilden eine Verbindung. Jede aktivierte Prüfung muss unabhängig bestanden werden, damit die Verbindung erfolgreich ist.

--ca-cert bereitgestellt	--pinnedpubkey bereitgestellt	Zum Akzeptieren erforderlich
nein	nein	Systemvertrauen validiert den Server (aktuelles Verhalten)
ja	nein	Der Server validiert anhand der Systemvertrauensstellung oder eines bereitgestellten Stammverzeichnisses
nein	ja	Die Systemvertrauenswürdigkeit überprüft, ob der Server und der öffentliche Blattschlüssel mit dem Pin übereinstimmen
ja	ja	Vertrauenspfad validiert und der öffentliche Blattschlüssel stimmt mit dem Pin überein

Die Hostnamenprüfung wird immer für den alternativen Antragstellernamen des Blattzertifikats (oder den allgemeinen Namen, wenn kein SAN vorhanden ist) durchgeführt, unabhängig davon, welche anderen Flags Sie festlegen.

---

Szenarien

Herstellen einer Verbindung mit der UiPath Automation Suite

Automation Suite-Cluster generieren während der Installation ihr eigenes selbstsigniertes UiPath AS Root CA -Zertifikat. Um das Hostzertifikat des Clusters zu validieren, exportieren Sie dieses Stammzertifikat und übergeben Sie es über --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

CI-/CD-Ausführung ohne Berechtigung zum systemweiten Installieren von Zertifikaten

CI/CD-Agents werden häufig als Dienstkonten von Nicht-Administratoren ausgeführt, die den Vertrauensspeicher des Betriebssystems nicht ändern können. --ca-cert definiert die Vertrauensstellung nur auf den aktuellen CLI-Aufruf.

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"

Der Agent benötigt nur Lesezugriff auf die Zertifikatdatei – keine erhöhten Berechtigungen, keine Änderungen am Maschinenstatus.

Mehrere Orchestrator-Ziele in einer einzelnen Pipeline

Wenn eine Pipeline in mehreren Orchestrator-Instanzen bereitgestellt wird, die von verschiedenen internen Zertifizierungsstellen signiert wurden, stellen Sie den Stamm jedes Clusters auf einmal bereit. Der Systemvertrauensspeicher gilt weiterhin, sodass öffentliche Orchestrator in derselben Pipeline ohne weitere Konfiguration weiterarbeiten.

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"

vertiefte Sicherheit auf einem öffentlich vertrauenswürdigen Server

Selbst wenn der Server von einer öffentlichen Zertifizierungsstelle signiert wurde, der das Betriebssystem bereits vertraut, können Sie den öffentlichen Schlüssel anheften, um eine Kompatibilität einer Zertifizierungsstelle im Vertrauensspeicher des Systems zu erkennen. Wenn ein falsch ausgestelltes Zertifikat für denselben Hostnamen präsentiert wird, weist der Pin es zurück, obwohl die Kettenvalidierung bestanden hätte.

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

Anheften hinter einer privaten Zertifizierungsstelle

Wenn der Server eine private Zertifizierungsstelle verwendet, sind beide Flags erforderlich. Der Pin allein umgangen die Kettenvalidierung nicht.

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

Heften Sie die Dauerdauer über die gesamte Zertifikatsrotation hinweg an

Die Pin verfolgt den öffentlichen Schlüssel, nicht das Zertifikat. Wenn das Zertifikat des Servers erneuert wird, aber sein privater Schlüssel wiederverwendet wird, bleibt der SHA-256 von SubjectPublicKeyInfo gleich und Ihr Pin funktioniert weiter. Wenn der Server ein neues Schlüsselpaar generiert, bricht die Pins und Sie müssen es neu berechnen und aktualisieren.

Insbesondere für die Automation Suite hängt das Verhalten der Zertifikatsrotation von der cert-manager -Konfiguration des Clusters ab. Testen Sie einmal nach der ersten Rotation: Wenn die neu berechnete Markierung mit der alten übereinstimmt, haben Sie bestätigt, dass der Cluster Schlüssel wiederverwendet und die Markierung dauerhaft ist; Wenn sie sich unterscheidet, wird der Pin bei jeder Rotation aktualisiert.

---

Fehlersuche und ‑behebung

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

Der relative Pfad wird für das aktuelle Arbeitsverzeichnis aufgelöst, und in diesem absoluten Pfad ist keine Datei vorhanden. Übergeben Sie entweder einen absoluten Pfad oder stellen Sie sicher, dass die CLI vom erwarteten Verzeichnis aus ausgeführt wird.

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

Die von Ihnen bereitgestellte PEM-Datei enthält zusätzlich zum Zertifikat einen privaten Schlüsselblock. Entfernen Sie den Schlüssel (er hat keine Rolle als Vertrauensanker) und versuchen Sie es erneut.

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

Die Datei ist höchstwahrscheinlich eine PFX/PKCS#12. Exportieren Sie ihn ohne den privaten Schlüssel erneut oder konvertieren Sie ihn mit openssl pkcs12 -in cert.pfx -nokeys -out cert.pem in PEM.

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

Die Zeichenfolge nach sha256// wurde nicht auf genau 32 Byte base64-decodiert. Berechnen Sie den Pin mithilfe eines der oben genannten Schemas neu.

Die Verbindung schlägt immer noch fehl, wobei --pinnedpubkey für einen internen Serverfestgelegt ist.

Der Pin allein umgangen die Kettenvalidierung nicht. Fügen Sie --ca-cert <root> hinzu, damit die Kette einen Vertrauensanker hat.