Verbinden Ihrer Server und Pipelines mit Uniqkey Secrets Manager über die uniqkey-CLI

Uniqkey Secrets Manager speichert die Geheimnisse, die Ihre Systeme verwenden: Datenbankpasswörter, API-Token, Verbindungszeichenfolgen und Zertifikate. Administratoren verwalten sie im Admin Portal. Server, Skripte und CI/CD-Pipelines lesen und schreiben sie mit dem Befehlszeilentool (CLI) uniqkey und einem API-Schlüssel. Dieser Artikel erklärt, wie Sie einen API-Schlüssel erstellen, die CLI installieren und konfigurieren, sie sicher verwenden und die häufigsten Probleme beheben.

Einige im gesamten Artikel verwendete Begriffe:

• Ein API-Schlüssel ist das Anmeldemittel, das eine Maschine verwendet. Er besteht aus zwei Teilen: einer Access Key ID (beginnt mit UKEY) und einem Secret Key (beginnt mit uksm_), der wie das Passwort des Schlüssels funktioniert.
• Ein Secret ist ein Wert, den Sie im Secrets Manager speichern.
• Ein Pfad bezeichnet ein einzelnes Secret, ähnlich wie eine Datei: /production/database/password. Ein Präfix ist der Anfang eines Pfads, z. B. /production, und umfasst alles darunter.

Wer kann dies verwenden?

• Secrets Manager muss für Ihre Organisation aktiviert sein. Wenn Sie Secrets Manager nicht im Menü des Admin Portals sehen, wenden Sie sich an den Uniqkey-Support.
• API-Schlüssel werden von einem Administrator der Organisation erstellt. Supportkonten und normale Mitarbeiter können Secrets Manager nicht öffnen.
• Ein API-Schlüssel gehört der Organisation, nicht dem Administrator, der ihn erstellt hat. Er funktioniert weiter, wenn dieser Administrator die Organisation verlässt. Ersetzen Sie daher die von einem ausscheidenden Administrator verwalteten Schlüssel.
• Die CLI läuft unter Windows, macOS und Linux (x64 und ARM). Sie ist ein einzelnes Programm, für das nichts weiter installiert werden muss.
• Die Maschine benötigt ausgehendes HTTPS (Port 443) zu secrets-manager.production.uniqkey.eu sowie zu static.uniqkey.eu für die Installation und Aktualisierung.

Schützen Sie Ihre API-Schlüssel und Secrets

• Secrets werden auf der Maschine, auf der die CLI ausgeführt wird, verschlüsselt und entschlüsselt. Uniqkey speichert nur verschlüsselte Werte und kann sie nicht lesen. Uniqkey kann den Pfad eines Secrets, den Zeitpunkt seiner Änderung und den API-Schlüssel sehen, der darauf zugegriffen hat. Geben Sie daher niemals vertrauliche Informationen in einen Pfad oder den Namen eines API-Schlüssels ein.
• Wer einen API-Schlüssel besitzt, kann alles entschlüsseln, was der Schlüssel lesen darf. Pfadeinschränkungen sind eine Berechtigung, die Uniqkey bei jeder Anfrage prüft, und keine separate Verschlüsselung: Es gibt einen Verschlüsselungsschlüssel pro Organisation. Geben Sie jedem Schlüssel den kleinstmöglichen benötigten Umfang und die kleinstmöglichen benötigten Pfade und legen Sie ein Ablaufdatum fest.
• Fügen Sie niemals einen Secret Key, eine Anmeldedatendatei, eine .env-Datei oder ein nicht anonymisiertes Protokoll in ein Ticket, eine E-Mail oder einen Chat ein. Der Uniqkey-Support benötigt diese niemals.
• Wenn ein API-Schlüssel möglicherweise offengelegt wurde: Deaktivieren oder löschen Sie ihn sofort auf der Seite API keys, ändern Sie jedes Secret, das der Schlüssel lesen konnte, an seiner Quelle (in der Datenbank oder beim Drittanbieterdienst), speichern Sie die neuen Werte und prüfen Sie das Audit-Protokoll auf Aktivitäten des Schlüssels. Frühere Werte bleiben im Versionsverlauf jedes Secrets erhalten.

Schritt 1: API-Schlüssel erstellen

1. Melden Sie sich als Administrator beim Admin Portal an.
2. Öffnen Sie Secrets Manager im Menü auf der linken Seite. Wenn das Portal Sie auffordert, die Anmeldung auf Ihrem Telefon zu bestätigen, genehmigen Sie die Anfrage innerhalb einer Minute in der Uniqkey-App. Für Secrets Manager muss Trusted Portal für Ihre Organisation zugelassen sein.
3. Öffnen Sie API keys im Menü auf der linken Seite und klicken Sie auf Create API Key.
4. Füllen Sie die Felder aus:
   • Name: Was wird den Schlüssel verwenden, z. B. ci-deploy-production. Der Name wird im Audit-Protokoll für alle Aktivitäten des Schlüssels angezeigt.
   • Scope: Read only, Read & write oder Admin (full access). Die meisten Pipelines benötigen Read only.
   • Path Restrictions: Die Präfixe, die der Schlüssel verwenden darf, z. B. /production. Lassen Sie das Feld nur dann leer, wenn der Schlüssel tatsächlich jedes Secret benötigt.
   • Expiry date (optional): empfohlen. Das früheste auswählbare Datum ist morgen. Der Schlüssel funktioniert bis zum Ende dieses Tages in der Zeitzone Ihres Browsers.
5. Klicken Sie auf Create. Der Dialog Copy your API key now zeigt die Access Key ID und den Secret Key an.
6. Kopieren Sie beide an den Ort, an dem die Maschine ihre Anmeldedaten speichert. Der Secret Key wird nur einmal angezeigt. Aktivieren Sie I have stored this API key in a safe place, um den Dialog zu schließen. Wenn der Secret Key verloren geht, löschen Sie den API-Schlüssel und erstellen Sie einen neuen.

API-Schlüssel später verwalten:

• Auf der Seite API keys werden alle Schlüssel mit ihrem Umfang, ihren Pfaden, ihrem Status, ihrem Ablaufdatum (Expires) und ihrer letzten Verwendung (Last used) aufgeführt. Dort kann ein Schlüssel deaktiviert, wieder aktiviert oder gelöscht werden. Beide Änderungen werden sofort wirksam.
• Eine Organisation kann höchstens 50 API-Schlüssel besitzen.
• Lesevorgänge, Änderungen und abgelehnte Anfragen werden im Audit-Protokoll der Organisation unter dem Thema Secrets Manager mit dem Namen des API-Schlüssels aufgezeichnet. Das Lesen eines gesamten Präfixes mit export oder run wird als ein Eintrag aufgezeichnet, der die Pfade auflistet.
• So wechseln Sie einen API-Schlüssel: Erstellen Sie einen neuen Schlüssel, aktualisieren Sie die Maschine, prüfen Sie, dass sich Last used des alten Schlüssels nicht mehr ändert, und löschen Sie anschließend den alten Schlüssel.

Schritt 2: CLI installieren

Windows (PowerShell):

irm https://static.uniqkey.eu/cli/install.ps1 | iex

macOS und Linux:

curl -fsSL https://static.uniqkey.eu/cli/install.sh | sh

Das Installationsprogramm lädt die richtige Version für die Maschine herunter und prüft sie vor der Installation anhand einer veröffentlichten Prüfsumme. Unter Windows ist das Programm von Uniqkey signiert. Das Installationsprogramm fügt es außerdem Ihrem PATH hinzu: Öffnen Sie anschließend ein neues Terminal. Unter macOS und Linux wird es in /usr/local/bin installiert oder in ~/.local/bin, wenn dieser Ordner nicht beschreibbar ist. Wenn das Installationsprogramm Sie auffordert, diesen Ordner zu Ihrem PATH hinzuzufügen, tun Sie dies.

Installation prüfen:

uniqkey version

Um eine bestimmte Version zu installieren, was in CI empfohlen wird, damit sich Builds nicht selbstständig ändern:

$env:UNIQKEY_VERSION = '1.0.1'; irm https://static.uniqkey.eu/cli/install.ps1 | iex

curl -fsSL https://static.uniqkey.eu/cli/install.sh | UNIQKEY_VERSION=1.0.1 sh

Aktualisieren: Führen Sie das Installationsprogramm erneut aus. Entfernen: Löschen Sie das Programm uniqkey und den Ordner .uniqkey in Ihrem Benutzerprofil. Dadurch werden auch gespeicherte Anmeldedaten entfernt. Wenn Ihre Sicherheitsrichtlinien das Ausführen eines heruntergeladenen Installationsskripts nicht erlauben, wenden Sie sich an den Uniqkey-Support, um einen direkten Download und die zugehörige Prüfsumme zu erhalten.

Schritt 3: CLI konfigurieren

Führen Sie auf einer Workstation oder einem Server Folgendes aus:

uniqkey configure

Sie werden nach drei Angaben gefragt. Drücken Sie bei API url die Eingabetaste, um die Produktionsadresse beizubehalten, und fügen Sie anschließend die Access key id und den Secret key ein. Der Secret Key wird beim Einfügen auf dem Bildschirm angezeigt. Führen Sie dies daher so aus, dass niemand Ihren Bildschirm sehen kann. Die Antworten werden in einer Anmeldedatendatei gespeichert:

• Windows: %USERPROFILE%\.uniqkey\credentials
• macOS und Linux: ~/.uniqkey/credentials

Die Datei enthält den Secret Key im Klartext. Bewahren Sie sie im Benutzerprofil des Kontos auf, das die CLI ausführt, kopieren Sie sie nicht zwischen Maschinen und fügen Sie sie niemals einer Quellcodeverwaltung oder einem Container-Image hinzu. Bewahren Sie Produktions-API-Schlüssel nur auf den Maschinen auf, die sie benötigen, nicht auf Entwickler-Laptops.

Die Datei kann mehrere Profile enthalten. Wählen Sie eines mit --profile (oder -p), das vor dem Befehl platziert wird, z. B. uniqkey -p build-server secret list, oder legen Sie die Umgebungsvariable UNIQKEY_PROFILE fest:

[default]
access_key_id = UKEYXXXXXXXXXXXXXXXX
secret_key = uksm_...

[build-server]
access_key_id = UKEYYYYYYYYYYYYYYYYY
secret_key = uksm_...

Erstellen Sie in CI/CD-Pipelines keine Anmeldedatendatei. Legen Sie diese Umgebungsvariablen stattdessen aus dem Secret-Speicher der Pipeline fest; sie haben Vorrang vor der Datei:

Die CLI verwendet standardmäßig die Produktionsadresse. Legen Sie die Adresse nur dann bei der Eingabeaufforderung API url von uniqkey configure oder in der Umgebungsvariable UNIQKEY_API_URL fest, wenn Uniqkey Ihnen eine andere Adresse mitgeteilt hat.

Wissenswertes über die Anmeldedatendatei:

• Schlüsselnamen unterscheiden nicht zwischen Groß- und Kleinschreibung. Ein Name, den die CLI nicht kennt, ist jedoch ein Fehler, sodass ein Tippfehler niemals stillschweigend ignoriert wird. Erstellen Sie das Profil mit uniqkey configure neu, wenn dieser Fehler auftritt.
• Wenn Sie die Datei in Windows PowerShell 5 mit > erstellen, kann die CLI sie nicht lesen. Verwenden Sie stattdessen uniqkey configure.
• uniqkey configure ändert nur das Profil, in das geschrieben wird, und lässt den Rest der Datei unverändert.

Schritt 4: Funktion prüfen

uniqkey secret list

Wenn der API-Schlüssel Secrets lesen kann, werden deren Pfade angezeigt. Wenn nichts aufgelistet wird, enthält keiner der zugewiesenen Pfade Secrets. Wenn ein Fehler auftritt, lesen Sie den Abschnitt „Fehlerbehebung“.

CLI verwenden

Ein Secret lesen:

uniqkey secret get /production/database/password

Ein Secret schreiben. Leiten Sie den Wert per Pipe weiter, anstatt ihn als Argument einzugeben, damit er nicht in Ihrem Shell-Verlauf erscheint:

# Windows (PowerShell): fragt nach dem Wert, der nicht im Verlauf gespeichert wird
Read-Host 'New value' | uniqkey secret set /production/database/password --overwrite

# macOS und Linux
openssl rand -base64 32 | uniqkey secret set /production/api/session-key --overwrite

Hinweise:

• Ein Zeilenumbruch am Ende eines weitergeleiteten Werts wird entfernt, sodass echo- und PowerShell-Pipes ohne besondere Optionen funktionieren.
• Beim Überschreiben bleiben Beschreibung, Tags und Typ erhalten, sofern Sie keine neuen angeben. Wenn jemand das Secret während der Ausführung des Befehls geändert hat, wird der Vorgang mit Exit-Code 6 beendet, anstatt die Änderung zu überschreiben. Führen Sie den Befehl erneut aus.
• Optionen wie --profile und --output json stehen vor dem Befehl (uniqkey --output json secret get /p); Optionen eines Befehls, z. B. --overwrite, stehen nach dem Pfad.
• Bei Pfaden wird zwischen Groß- und Kleinschreibung unterschieden.

Secrets an ein Programm übergeben

uniqkey run ist die sicherste Methode, Secrets an ein Programm zu übergeben: Sie gelangen direkt in dessen Umgebung und werden niemals ausgegeben oder auf der Festplatte gespeichert.

uniqkey run /production/api -- <your command>

• Jedes Secret wird zu einer Umgebungsvariablen, die nach dem Teil des Pfads unterhalb des Präfixes benannt, in Großbuchstaben geschrieben und mit anderen Zeichen in _ umgewandelt wird: Unter /production/api wird /production/api/stripe-key zu STRIPE_KEY.
• Wenn zwei Secrets denselben Namen erhalten würden oder ein Name die Art des Programmstarts ändern würde (z. B. PATH), wird der Befehl beendet, bevor etwas ausgeführt wird. Benennen Sie das Secret um.
• Die Variablen UNIQKEY_ACCESS_KEY_ID und UNIQKEY_SECRET_KEY werden nicht an das Programm weitergegeben.
• run wird mit dem Exit-Code des ausgeführten Programms beendet.

Secrets in eine Shell oder .env-Datei laden

uniqkey export gibt die Secrets als Anweisungen für eine Shell aus. Das Standardformat ist unter Windows PowerShell und unter macOS und Linux eine POSIX-Shell.

# Windows (PowerShell)
uniqkey export /production/api | Out-String | iex

# macOS und Linux (bash, zsh, sh); in Git Bash unter Windows --format posix hinzufügen
eval "$(uniqkey export /production/api)"

# Docker-Compose-.env-Datei (macOS und Linux)
(umask 077; uniqkey export /production/api --format dotenv > .env)

• export gibt Secrets im Klartext aus. Verwenden Sie es nur, wenn die Ausgabe sofort verarbeitet wird, und bevorzugen Sie run.
• Eine .env-Datei enthält jedes Secret unter dem Präfix im Klartext. Halten Sie sie aus der Quellcodeverwaltung heraus (fügen Sie sie zu .gitignore hinzu), beschränken Sie den Lesezugriff auf sich selbst und löschen Sie sie, wenn Sie fertig sind. Erstellen Sie sie unter Windows aus cmd (cmd /c "uniqkey export /production/api --format dotenv > .env"), da Windows PowerShell 5 die Ausgabe von > in einem Format schreibt, das Docker Compose nicht lesen kann.
• Das .env-Format ist für Tools gedacht, die .env-Dateien lesen, z. B. Docker Compose. Es ist kein Shell-Skript: Laden Sie es niemals mit source oder . .env, da ein Wert mit Anführungszeichen, $ oder Backticks andernfalls Befehle ausführen kann.
• In PowerShell werden akzentuierte Zeichen, Emojis und Zeilenumbrüche unverändert übernommen, auch auf gesperrten Maschinen. Ein leeres Secret entfernt die Variable, anstatt sie auf einen leeren Wert zu setzen.
• Wenn das Präfix keinem Secret entspricht, gibt die CLI eine Warnung aus und erzeugt keine Ausgabe; in PowerShell zeigt der Schritt iex anschließend einen Fehler über eine leere Zeichenfolge an. Prüfen Sie das Präfix und die Pfade des API-Schlüssels.

Verwendung in CI/CD

1. Speichern Sie die Access Key ID und den Secret Key als geheime Variablen in der Pipeline und ordnen Sie sie UNIQKEY_ACCESS_KEY_ID und UNIQKEY_SECRET_KEY zu.
2. Installieren Sie anhand der Befehle in Schritt 2 eine festgelegte CLI-Version.
3. Führen Sie Ihren Schritt über uniqkey run /production/api -- <your deploy command> aus.

Die Pipeline maskiert die beiden API-Schlüsselvariablen in ihren Protokollen, kennt jedoch die Werte nicht, die die CLI zur Laufzeit abruft. Bevorzugen Sie run, wodurch diese nicht im Protokoll erscheinen. Wenn Sie Werte ausgeben oder export verwenden, maskieren Sie sie ausdrücklich in Ihrem CI-System und verwenden Sie für diese Schritte nicht set -x, env oder die Debug-Protokollierung. Führen Sie uniqkey configure nicht in einer Pipeline aus.

Kubernetes

Für Kubernetes enthält die CLI einen kleinen Proxy namens uniqkey serve, über den der External Secrets Operator liest. Er entschlüsselt innerhalb Ihres Clusters, sodass Anwendungen ein normales Kubernetes-Secret erhalten. Verwenden Sie einen auf Read only beschränkten API-Schlüssel, der nur auf die vom Cluster benötigten Präfixe zugreifen kann, führen Sie den Proxy mit einem TLS-Zertifikat aus und verwenden Sie eine NetworkPolicy, sodass nur der External Secrets Operator darauf zugreifen kann. Die resultierenden Kubernetes-Secrets werden in Ihrem Cluster im Klartext gespeichert, sofern Sie keine Verschlüsselung im Ruhezustand aktivieren. Wenden Sie sich an den Uniqkey-Support, um die Bereitstellungsmanifeste zu erhalten.

Exit-Codes

Jeder Befehl wird mit einem Code beendet, den ein Skript prüfen kann. Fehlermeldungen werden an die Fehlerausgabe gesendet und beginnen mit uniqkey:; Werte werden an die normale Ausgabe gesendet. uniqkey run wird mit dem Code des ausgeführten Programms beendet.

Limits

Jeder CLI-Befehl entsperrt zunächst die Verschlüsselung der Organisation, was auf das IP-Limit angerechnet wird. Alle Maschinen, die Uniqkey über dieselbe öffentliche IP-Adresse erreichen (z. B. hinter einem NAT oder Proxy), teilen sich dieses Limit. Daher kann eine Pipeline, die uniqkey secret get viele Male pro Minute ausführt, einer Ratenbegrenzung unterliegen, obwohl jeder API-Schlüssel deutlich unter seinem eigenen Limit liegt. Lesen Sie ein ganzes Präfix mit einem einzigen run- oder export-Befehl, anstatt viele secret get-Aufrufe auszuführen.

Fehlerbehebung

Wenn Sie den Support kontaktieren, geben Sie den Namen Ihrer Organisation, die Ausgabe von uniqkey version, das Betriebssystem, den genauen Befehl ohne vertrauliche Werte, die vollständige Fehlermeldung, den Exit-Code (echo $? in bash, $LASTEXITCODE in PowerShell), den Namen des API-Schlüssels (niemals den Secret Key) und den Zeitpunkt des Vorfalls an.