Secrets

Was ist das

Ein Secret ist ein benannter Wert, ein Passwort oder ein Token, den WERKSPUR verschlüsselt speichert. Verschlüsselt wird mit AES-256-GCM, einem authentifizierten Verfahren: Ein manipulierter Geheimtext fällt beim Entschlüsseln auf, statt unbemerkt einen falschen Wert zu liefern. Nach dem Speichern ist der Wert für niemanden mehr lesbar, auch nicht für Admins.

Die API kennt nur Namen: anlegen, auflisten, löschen. Sie liefert nie einen gespeicherten Wert zurück, auch nicht an einen angemeldeten Admin. Ein Secret verwenden Sie deshalb ausschließlich über einen Namens-Verweis in einem anderen Artefakt, etwa an einem Zielsystem oder einem Trigger, nie über den Wert selbst.

Wann einsetzen

Überall dort, wo ein Artefakt Zugangsdaten braucht:

Am Zielsystem. auth.secret trägt den Namen des Secrets für die Authentifizierung bei rest.call, soap.call oder einer AMQP-Verbindung. Der Benutzername darf offen in der Definition stehen, das Passwort nie.
Am Trigger. webhook.secret sichert einen eingehenden Webhook ab. Nur wer den passenden Wert als Bearer-Header mitschickt, löst die Aktion aus.
Am OPC-UA-Ziel. password_secret, user_cert_secret und user_key_secret tragen Passwort- beziehungsweise Zertifikats-Secrets für die Verbindung zur Maschine.

Der Wert steht damit an genau einer Stelle im System, nicht verstreut über mehrere Definitionen. Ändert sich das Passwort beim externen System, passen Sie das Secret einmal an; jedes Zielsystem, jeder Trigger und jedes OPC-UA-Ziel, das darauf verweist, nutzt ab dem nächsten Aufruf automatisch den neuen Wert.

Anatomie

Ein Secret ist kein JSON-Artefakt wie eine Aktion oder ein Trigger. Ein Admin trägt Namen und Wert unter „Secrets“ ein. Dafür gibt es weder eine Datei noch einen Assistentenvorschlag. Die Verwaltungsseite zeigt nach dem Anlegen nur noch den Namen an, nicht den Wert.

Der Server benötigt dafür einen eigenen Schlüssel: FOUNDRY_SECRET_KEY, base64-kodiert und 32 Byte lang, oder eine über FOUNDRY_SECRET_KEY_FILE angegebene Datei. Fehlt dieser Schlüssel, lehnt der Server das Anlegen eines Secrets mit Status 503 ab, statt den Wert unverschlüsselt zu speichern.

Existiert bereits mindestens ein Secret in der Datenbank und fehlt der Schlüssel beim Start, startet der Server nicht mit den unentschlüsselbaren Werten. Legen Sie ein Secret unter einem vorhandenen Namen erneut an, überschreibt die API seinen Wert. Sie unterscheidet dabei nicht zwischen einem neuen Namen und einem vorhandenen Eintrag.

Auch der Assistent hält diese Grenze ein. Er kann Secret-Werte weder lesen noch schreiben. Schlägt er eine Definition vor, die ein Secret benötigt, verweist er nur auf dessen Namen und verlinkt die Seite „Secrets“, auf der Sie den Wert selbst eintragen.

Beispiele

{
  "name": "broker",
  "kind": "amqp",
  "base_url": "amqp://broker.werk.local:5672/",
  "username": "werkspur",
  "auth": {
    "header": "",
    "secret": "broker-passwort"
  }
}

Mit dem Assistenten

Broker-Zugang ohne Passwort in der Konfiguration.

Das Zielsystem broker trägt username: werkspur offen in seiner Definition, das Passwort dagegen nur als Namens-Verweis: auth.secret: broker-passwort. Den tatsächlichen Wert löst WERKSPUR erst beim Verbindungsaufbau zum Broker auf. Ist das Secret nicht vorhanden oder nicht auflösbar, scheitert die Verbindung, statt ohne Passwort zu senden.

{
  "name": "erp-auftrag-webhook",
  "summary": "Externes System stößt die Fertigmeldung eines Loses an",
  "type": "webhook",
  "webhook": {
    "secret": "erp-webhook-secret"
  },
  "action": "fertigmeldung",
  "inputs": {
    "lot": "${body.lot}",
    "order": "${body.order_number}",
    "qty": "${body.qty}"
  },
  "run_as": "planner",
  "enabled": true
}

Mit dem Assistenten

Webhook absichern.

webhook.secret nennt nur den Namen erp-webhook-secret, nie dessen Wert. Ruft das ERP-System den Webhook auf, schickt es den Wert dieses Secrets als Bearer-Header mit. WERKSPUR löst das Secret auf und vergleicht den Header dagegen; ohne Treffer lehnt es den Aufruf ab, bevor die Aktion überhaupt läuft.

Fallstricke

Ein gelöschtes Secret macht jeden Verweis ungültig. Ein Zielsystem, ein Trigger oder ein OPC-UA-Ziel, das ein gelöschtes Secret referenziert, schlägt beim nächsten Aufruf fehl. Ein Umbenennen kennt die API nicht: Legen Sie das Secret unter dem neuen Namen an, stellen Sie alle Verweise um und löschen Sie danach den alten Eintrag.
Ein Wert lässt sich nicht anzeigen, nur überschreiben. Wer den Wert eines Secrets verliert, kann ihn nicht nachschlagen. Er hinterlegt ihn unter demselben Namen neu.
Erst das Secret, dann das Artefakt. Legen Sie das Secret an, bevor Sie es in einem Zielsystem, einem Trigger oder einem OPC-UA-Ziel referenzieren. Die Validierung dieser Artefakte prüft, ob der genannte Name existiert, und lehnt eine Definition mit einem unbekannten Secret-Namen ab.

Wie ein Zielsystem sein Secret referenziert, zeigt das Kapitel Zielsysteme. Wie ein Webhook-Trigger seinen Bearer-Wert prüft, beschreibt das Kapitel Trigger. Wie ein OPC-UA-Ziel Passwort- und Zertifikats-Secrets für die Verbindung zur Maschine nutzt, erklärt das Kapitel OPC UA.