Push-Benachrichtigungen aus jedem Skript – die Appliance als Alarmkanal

Die Notakey Appliance wird meist als Authentifizierungsserver beschrieben: Eine Anmeldung findet statt, eine Push-Anfrage erscheint auf dem Telefon, der Benutzer genehmigt sie. Derselbe Zustellkanal nimmt aber noch einen zweiten Nachrichtentyp entgegen, eine schlichte Benachrichtigung, und macht die Appliance damit zu etwas Allgemeinerem: einem Push-Kanal zu jedem in Ihrem Dienst registrierten Telefon, erreichbar aus jedem Skript mit einem einzigen curl.

any script ──HTTPS──▶ appliance API ──push──▶ enrolled phone
 (cron, monitoring,    /notify                 Notakey Authenticator
  home automation…)

Anders als eine Authentifizierungsanfrage verlangt eine Benachrichtigung keine Genehmigung: Sie erscheint einfach auf dem Telefon, adressiert an einen Benutzernamen, und wird gleichzeitig an alle registrierten Geräte des Benutzers zugestellt. Damit ist sie ein direkter Ersatz überall dort, wo Sie sonst SMS (Kosten pro Nachricht, fälschbarer Absender) oder E-Mail (bleibt bis Montag ungelesen) anbinden würden: Job-Überwachung, Bereitschaftsalarme, Mitteilungen an die Belegschaft.

Voraussetzungen

Eine laufende Notakey Appliance (Cloud oder on-premise) mit einem Dienst und mindestens einem Benutzer mit registriertem Telefon. Wenn Sie bereits VPN-2FA oder SSO betreiben, haben Sie all das. Benachrichtigungen laufen über denselben Dienst wie Ihre Anmeldungen, oder über einen eigenen, wenn Sie ein anderes Branding wünschen.
API-Anmeldedaten (eine Client-ID und ein Client-Secret), erstellt im Dashboard unter Access credentials (siehe Schritt 1).
curl und jq auf irgendeinem System, das die Appliance erreicht. Das ist die gesamte Abhängigkeitsliste.

Schritt 1: API-Anmeldedaten erstellen

Öffnen Sie im Dashboard Access credentials und legen Sie Anmeldedaten für Ihre Skripte an. Zwei Dinge sind hier wichtig:

Scopes. Erteilen Sie urn:notakey:notify, den Scope, den diese Anleitung benötigt. Es gibt auch urn:notakey:auth zum Erstellen von Authentifizierungsanfragen (genehmigen/ablehnen); fügen Sie ihn nur hinzu, wenn dieselben Anmeldedaten beides tun sollen. Anmeldedaten, die nur benachrichtigen dürfen, lassen sich nicht missbrauchen, um Anmeldegenehmigungen auszulösen. Halten Sie die Scope-Liste daher so kurz, wie es die Aufgabe erlaubt.
Sie erhalten eine Client-ID und ein Client-Secret. Das Secret berechtigt dazu, allen Benutzern des Dienstes Nachrichten zu senden – behandeln Sie es wie ein Root-Passwort.

Schritt 2: Anmeldedaten gegen ein Token tauschen und das Token frisch halten

Der Notify-Aufruf selbst verwendet nicht das Client-Secret, sondern ein Bearer-Zugriffstoken, bezogen über den standardmäßigen OAuth-2.0-Client-Credentials-Grant. Zugriffstokens sind bewusst kurzlebig: Planen Sie eine Erneuerung etwa einmal pro Stunde ein, sonst schlagen Ihre Skripte, nachdem sie 59 Minuten lang einwandfrei liefen, irgendwann mit Autorisierungsfehlern fehl.

Die Token-Erneuerung ist deshalb ein cron-Job, kein einmaliger Einrichtungsschritt:

#!/bin/bash
# /usr/local/bin/ntk-token-renew — cron: 0 * * * *

curl -s -X POST https://ntk.example.com/api/token \
  -d 'grant_type=client_credentials&client_id=<client-id>&client_secret=<client-secret>&scope=urn:notakey:notify' \
  | jq -r .access_token > /etc/notakey/api.token

Das Skript enthält das Client-Secret und schreibt das Token. Sichern Sie deshalb beides ab:

chmod 700 /usr/local/bin/ntk-token-renew    # root-only, holds the secret
install -m 600 /dev/null /etc/notakey/api.token

Wenn Sie zusätzlich urn:notakey:auth erteilt haben, fordern Sie es als separates Token in eine separate Datei an (gleicher Aufruf, scope=urn:notakey:auth) statt eines einzigen Tokens mit beiden Scopes. Die Benachrichtigungsskripte halten dann nie ein Token, mit dem sich Anmeldegenehmigungen erzeugen ließen.

Schritt 3: Ein wiederverwendbares Notify-Skript

Alles Weitere in dieser Anleitung ruft dieses eine Skript auf. Es erwartet einen Benutzernamen, einen Titel und einen Nachrichtentext:

#!/bin/bash
# /usr/local/bin/ntk-notify <username> <title> <description>

token=$(cat /etc/notakey/api.token)

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -d '{ "username": "'"$1"'", "title": "'"$2"'", "description": "'"$3"'", "type": "notification" }' \
  "https://ntk.example.com/api/v3/services/<service-id>/notify"

Ersetzen Sie ntk.example.com durch die Adresse Ihrer Appliance und <service-id> durch die Dienst-UUID aus dem Dashboard. Testen Sie es:

ntk-notify j.doe "Test" "If you can read this on your phone, the channel works."

Die Push-Nachricht kommt in der App Notakey Authenticator an, derselben App, die der Benutzer bereits für Anmeldungen nutzt. Es gibt also nichts Neues zu installieren, zu erklären oder am Mobile-Device-Management vorbei freizugeben.

Schritt 4: Von überall aufrufen

Sobald der Kanal ein Einzeiler ist, sammeln sich die Anwendungsfälle von selbst an. Einige, die heute produktiv laufen:

Ein Backup-Job, der sich zurückmeldet. Der Klassiker unter den unbemerkten Ausfällen: Backups, die vor Monaten aufgehört haben zu funktionieren, ohne dass es jemand gemerkt hat. Zwei Zeilen am Ende des Jobs schaffen Abhilfe:

if ! /usr/local/bin/backup-run; then
  ntk-notify admin "Backup FAILED" "Nightly backup on $(hostname) exited with an error — check /var/log/backup.log"
fi

Festplattenplatz, Zertifikatsablauf – alles, was cron prüfen kann:

#!/bin/bash
# cron: 0 8 * * *
used=$(df --output=pcent / | tail -1 | tr -dc '0-9')
if [ "$used" -gt 90 ]; then
  ntk-notify admin "Disk warning" "Root filesystem on $(hostname) is at ${used}% — time to clean up."
fi

Eine Mitteilung an alle Mitarbeiter. Die API adressiert einen Benutzernamen pro Aufruf; eine unternehmensweite Nachricht ist also eine Schleife über Ihre Benutzerliste. Wartungsfenster, Büroschließungen, Störungsmeldungen:

while read -r user; do
  ntk-notify "$user" "IT maintenance" "VPN unavailable Saturday 06:00–08:00 — planned appliance upgrade."
done < users.txt

Strom-Spotpreise, zwei Preise alle zwei Stunden. Nicht alles, was einen Push wert ist, ist ein Ausfall. Dieses Skript läuft per cron und sagt dem Benutzer, was die nächste Stunde Strom kosten wird – praktisch, um zu entscheiden, wann die Spülmaschine laufen soll:

#!/bin/bash
# cron: 5 * * * * — sends on even hours, 06–23 only
hour=$(( $(date +%H) + 1 ))
next=$(( hour + 1 ))

if [ "$hour" -gt 5 ] && [ "$hour" -lt 24 ] && (( $(date +%H) % 2 == 0 )); then
  ntk-notify "$1" "Electricity" \
    "Next hour: $(spot_price "$hour")€/kWh. After that: $(spot_price "$next")€/kWh."
fi

(spot_price steht für das, was Ihre Marktdaten beschafft: eine Börsen-API, eine CSV-Datei im Cache. Entscheidend ist die Zustellung, nicht die Quelle.)

Für wiederkehrende Nachrichten wie diese lohnt es sich, zwei dokumentierte Extras zu kennen. Mit einem fingerprint-Feld im Payload aktualisiert ein erneuter Versand mit demselben Fingerprint die bestehende Nachricht, statt eine neue darüberzustapeln; ein Preisticker bleibt so eine einzige Benachrichtigung statt vierzig am Tag. Und "type": "sms" verschickt dieselbe Nachricht stattdessen als SMS, sofern für den Benutzer eine Mobilnummer hinterlegt ist – ein Ausweichkanal für jemanden, auf dessen Telefon die App fehlt.

Wofür dieser Kanal taugt – und wofür nicht

Verglichen mit SMS ist die Empfängerseite deutlich stärker: Eine SMS landet auf dem Gerät, in dem gerade die SIM-Karte steckt, mit einem Absendernamen, den jeder fälschen kann. Eine Notakey-Benachrichtigung dagegen erscheint nur in der Authenticator-App auf Geräten, die die kryptografische Registrierung in Ihrem Dienst abgeschlossen haben. Niemand kann Ihre Alarme selbst abonnieren, und niemand kann den Absender fälschen.

Eine ehrliche Einschränkung, direkt aus der API-Dokumentation: Der Nachrichtentext selbst ist nicht Ende-zu-Ende-verschlüsselt. Wie jede mobile Push-Nachricht läuft er über die Push-Dienste von Apple und Google und ist auf dem Gerät für Apps mit Benachrichtigungszugriff lesbar. Behandeln Sie den Nachrichtentext deshalb wie eine Pager-Meldung, nicht wie einen versiegelten Umschlag: „Backup auf Host X fehlgeschlagen“ ist in Ordnung; ein Passwort oder ein API-Schlüssel nicht. Wenn Sie etwas wirklich Geheimes übermitteln müssen, verwenden Sie stattdessen eine Authentifizierungsanfrage (urn:notakey:auth): Dort ist der Push nur ein Klopfen an der Tür, und die eigentlichen Inhalte holt sich die App nach der Reaktion des Benutzers über ihren zertifikatsauthentifizierten Kanal.

Wo das hineinpasst

Wenn die Appliance bereits Ihr VPN oder Ihre Anwendungen schützt, sind Benachrichtigungen eine Funktion, die Sie kostenlos mitbekommen und bisher nicht nutzen: derselbe Dienst, dieselbe App, dieselben API-Anmeldedaten, ein zusätzlicher Endpunkt. Und wenn Sie bislang ein SMS-Gateway für interne Alarme bezahlt haben, ersetzt dieser Kanal es für jeden Empfänger, der ein registriertes Telefon bei sich trägt.