Programmgesteuerte API-Schlüsselverwaltung

Diese Anleitung erklärt, wie man API-Schlüssel mit der Unraid API CLI programmgesteuert erstellt, verwendet und löscht, um automatisierte Workflows und Skripte zu ermöglichen.

Übersicht

Der Befehl unraid-api apikey unterstützt sowohl interaktive als auch nicht-interaktive Modi und eignet sich für:

• Automatisierte Bereitstellungsskripte
• CI/CD-Pipelines
• Temporäre Zugangsbereitstellung
• Infrastruktur-als-Code-Workflows

Quick Start

Springen Sie zum kompletten Workflow-Beispiel, um alles in Aktion zu sehen.

Programmatische Erstellung von API-Schlüsseln

Grundlegende Erstellung mit JSON-Ausgabe

Verwenden Sie das --json-Flag, um maschinenlesbare Ausgabe zu erhalten:

unraid-api apikey --create --name "workflow key" --roles ADMIN --json

Ausgabe:

{
 "key": "ihr-generierter-api-schlüssel-hier",
 "name": "workflow key",
 "id": "generierte-uuid"
}

Erweiterte Erstellung mit Berechtigungen

unraid-api apikey --create \
 --name "eingeschränkter Zugriff Schlüssel" \
 --permissions "DOCKER:READ_ANY,ARRAY:READ_ANY" \
 --description "Nur-Lesezugriff für Überwachung" \
 --json

Umgang mit bestehenden Schlüsseln

Verwenden Sie --overwrite, wenn ein Schlüssel mit demselben Namen existiert:

unraid-api apikey --create --name "bestehender schlüssel" --roles ADMIN --overwrite --json

Key Ersatz

Das --overwrite-Flag wird den vorhandenen Schlüssel dauerhaft ersetzen. Der alte Schlüssel wird sofort ungültig gemacht.

Programmatisches Löschen von API-Schlüsseln

Nicht-interaktive Löschung

Löschen Sie einen Schlüssel nach Namen ohne Aufforderungen:

unraid-api apikey --delete --name "workflow key"

Ausgabe:

Erfolgreich 1 API-Schlüssel gelöscht

JSON-Ausgabe für das Löschen

Verwenden Sie das --json-Flag für maschinenlesbare Löschbestätigung:

unraid-api apikey --delete --name "workflow key" --json

Erfolgs-Ausgabe:

{
 "deleted": 1,
 "keys": [
 {
 "id": "generierte-uuid",
 "name": "workflow key"
 }
 ]
}

Fehlerausgabe:

{
 "deleted": 0,
 "error": "Kein API-Schlüssel mit dem Namen gefunden: nicht vorhandener Schlüssel"
}

Fehlerbehandlung

Wenn der angegebene Schlüssel nicht existiert:

unraid-api apikey --delete --name "nicht vorhandener Schlüssel"
# Ausgabe: Keine API-Schlüssel zum Löschen gefunden

JSON Fehlerausgabe:

{
 "deleted": 0,
 "message": "Keine API-Schlüssel zum Löschen gefunden"
}

Komplettes Workflow-Beispiel

Hier ist ein vollständiges Beispiel zur Bereitstellung von temporärem Zugriff:

#!/bin/bash
set -e

# 1. Temporären API-Schlüssel erstellen
echo "Temporären API-Schlüssel erstellen..."
KEY_DATA=$(unraid-api apikey --create \
 --name "temporärer Bereitstellungsschlüssel" \
 --roles ADMIN \
 --description "Temporärer Schlüssel für Bereitstellung $(date)" \
 --json)

# 2. API-Schlüssel extrahieren
API_KEY=$(echo "$KEY_DATA" | jq -r '.key')
echo "API-Schlüssel erfolgreich erstellt"

# 3. Schlüssel für Operationen verwenden
echo "Dienste konfigurieren..."
curl -H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"provider": "azure", "clientId": "your-client-id"}' \
 http://localhost:3001/graphql

# 4. Aufräumen (läuft immer, auch bei Fehler)
trap 'echo "Aufräumen..."; unraid-api apikey --delete --name "temporärer Bereitstellungsschlüssel"' EXIT

echo "Bereitstellung erfolgreich abgeschlossen"

Befehlsübersicht

Befehlserstellungsoptionen

Flagge	Beschreibung	Beispiel
--name <name>	Schlüsselname (erforderlich)	--name "mein Schlüssel"
--roles <roles>	Komma-getrennte Rollen	--roles ADMIN,VIEWER
--permissions <perms>	Ressource:Aktionspaare	--permissions "DOCKER:READ_ANY"
--description <desc>	Schlüsselbeschreibung	--description "CI/CD Schlüssel"
--overwrite	Existierenden Schlüssel ersetzen	--overwrite
--json	Maschinenlesbare Ausgabefunktion	--json

Verfügbare Rollen

• ADMIN - Voller Systemzugang
• CONNECT - Unraid Connect Funktionen
• VIEWER - Nur-Lesezugriff
• GUEST - Eingeschränkter Zugriff

Verfügbare Ressourcen und Aktionen

Ressourcen: ACTIVATION_CODE, API_KEY, ARRAY, CLOUD, CONFIG, CONNECT, CONNECT__REMOTE_ACCESS, CUSTOMIZATIONS, DASHBOARD, DISK, DISPLAY, DOCKER, FLASH, INFO, LOGS, ME, NETWORK, NOTIFICATIONS, ONLINE, OS, OWNER, PERMISSION, REGISTRATION, SERVERS, SERVICES, SHARE, VARS, VMS, WELCOME

Aktionen: CREATE_ANY, CREATE_OWN, READ_ANY, READ_OWN, UPDATE_ANY, UPDATE_OWN, DELETE_ANY, DELETE_OWN

Befehlslöschungsoptionen

Flagge	Beschreibung	Beispiel
--delete	Löschmodus aktivieren	--delete
--name <name>	Zu löschender Schlüssel (optional)	--name "mein Schlüssel"

Hinweis: Wenn --name weggelassen wird, wird der Befehl interaktiv ausgeführt.

Beste Praktiken

Security Beste Praktiken

Minimale Berechtigungen

• Spezifische Berechtigungen anstelle der ADMIN-Rolle verwenden, wenn möglich
• Beispiel: --permissions "DOCKER:READ_ANY" anstelle von --roles ADMIN

Schlüssel-Lebenszyklus-Management

• Temporäre Schlüssel immer nach Gebrauch bereinigen
• API-Schlüssel sicher speichern (Umgebungsvariablen, Geheimnismanagement)
• Verwenden Sie beschreibende Namen und Beschreibungen für Prüfpfade

Fehlerbehandlung

• Überprüfen Sie Exit-Codes ($?) nach jedem Befehl
• Verwenden Sie set -e in Bash-Skripten, um bei Fehlern schnell zu scheitern
• Führen Sie eine ordnungsgemäße Reinigung mit trap durch

Schlüsselbenennung

• Verwenden Sie beschreibende Namen, die Zweck und Datum enthalten
• Namen müssen nur Buchstaben, Zahlen und Leerzeichen enthalten
• Unicode-Buchstaben werden unterstützt

Fehlerbehebung

Häufige Probleme

Common Fehlermeldungen

"API-Schlüsselname darf nur Buchstaben, Zahlen und Leerzeichen enthalten"

• Lösung: Entfernen Sie Sonderzeichen wie Bindestriche, Unterstriche oder Symbole

"API-Schlüssel mit Namen 'x' existiert bereits"

• Lösung: Verwenden Sie das --overwrite-Flag oder wählen Sie einen anderen Namen

"Bitte fügen Sie mindestens eine Rolle oder Berechtigung zum Schlüssel hinzu"

• Lösung: Geben Sie entweder --roles oder --permissions an (oder beides)

Debug-Modus

Führen Sie für die Fehlerbehebung mit Debug-Protokollierung aus:

LOG_LEVEL=debug unraid-api apikey --create --name "debug key" --roles ADMIN